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Preface 


This manual describes how to use the services provided by the Application 
Program Interface (API) for the IBM 3270 Workstation Program (also 
referred to as the workstation program). 


This book consists of five parts: 


e The chapters in Part 1 introduce the Application Program Interface 
(API) and the two types of services you can use: 


— Application program services that most application programs will 
use. Described also are some supervisor services that directly 
support the application program services. 


— Those supervisor services that allow application programs to run 
together under the multitasking capabilities of the workstation 
program. 


e The chapters in Part 2 tell you how to invoke the application program 
services. A sample block of code is provided for each service, so that 
you can see how it is used in context. 


e The chapters in Part 3 describe, and tell you how to invoke, the 
supervisor services. A sample block of code is provided for each 
service, so that you can see how it is coded in context. 


e The chapters in Part 4 contain representative sample programs using 
most of the services described in Parts 2 and 3. 


e Part 5 consists of appendixes with specialized information. In 
particular, Appendix A provides information on scan codes and shift 
states for all supported keyboards. Appendix A also contains 
ASCII/ASCII-mnemonic values common to all languages and the 
additional values specific to U.S. English. 


You will also want to use Appendix H, “Return Codes.” 
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Enhancements 


The 3270 Workstation Program Programming Guide contains revisions to 
the 8270 PC Control Program Programming Guide, and incorporates the 
following new material: 


e Non-3270 PC Hardware. IBM Personal Computer AT® and XT system 
units, without the keyboard adapter and 3270 PC display adapter cards 
installed, are supported in this release. IBM Personal Computer AT 
and XT keyboard foldouts can be found at the back of this book. 


e ASCII keystroke API support. The Keyboard Service API allows 
applications to send and receive keys in ASCII or ASCII mnemonics. 
The 3270 Emulation Services API allows you to receive keystrokes in 
ASCII. Chapters 5 and 9 contain more information on ASCII keystroke 
API support. 


e Keystroke API Support for READ. Keystroke API support for READ 
now allows you to receive keys with a NOWAIT option which prevents 
you from being suspended while waiting for input on your queue. 


e Outbound Data Stream Preprocessor Option. ODSP allows the 
preprocessing of a 3270 outbound data stream which can reduce the 
amount of data traffic flowing through a network. See Appendix I for 
more information on ODSP. 


e SPIF Utility Enhancement. The SPIF utility has been enhanced to 
allow you to run an application that installs an interrupt handler which 
changes to its own stack and then enables interrupts. This may cause 
unpredictable results on systems with an XMA card installed unless you 
use the SPIF utility to update the INDIBM2.SIF file first. See the JBM 
3270 Workstation Program User’s Guide and Reference for more 
information about updating INDIBM2.SIF. 


Prerequisites for Your Using the API 
The API is written for application and system programmers who are 
responsible for the design and implementation of assembler-language 
programs for the IBM 3270 Personal Computer. 
To use the API, you must have available the following software: 
e DOS 3.2 
e The IBM 3270 Workstation Program 


e The IBM Macro Assembler or an equivalent assembler written for the 
Intel 8088 architecture. 


lv 


Prerequisite knowledge needed to be able to use the information in this 
manual includes: 


Proficiency in the use of the IBM Personal Computer Macro Assembler 
language 


Knowledge of the steps required to assemble, link, and run a macro 
assembler program on the IBM 3270 Personal Computer 


Familiarity with the DOS function calls that can be used in a macro 
assembler program 


Familharity with the IBM 3270 data stream. 


Related Publications 


The following books are related to the 3270 Workstation Program and its 
prerequisite hardware and software: 


Guide to Operations 


The Guide to Operations shipped with your system unit contains 
information about your work station hardware. It tells you how to set 
up, use, and diagnose problems with the hardware. 


3270 Personal Computer Hardware Introduction and Preinstallation 
Planning! 


This book contains information to help evaluate and plan for the 3270 
PC hardware requirements at your site. For example, it lists the 


physical dimensions and electrical requirements for all 3270 PC 
hardware models. 


The following items are shipped with the workstation program 
diskettes: 


— $8270 Workstation Program User’s Guide and Reference 


This book contains information about setting up and using the 
workstation program. 


— 8270 Workstation Program Problem Determination Guide and 
Reference 


Contact your local IBM sales representative for information on how to obtain 
copies of these books. 
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This book explains the procedures, messages, and return codes that 
will help you solve software problems. 


— 3270 Workstation Program Keyboard Quick Reference Cards 


These cards are keyboard-specific synopses of information from the 
User’s Guide and Reference. You can use the one that relates to 
your keyboard for quick reference. There are three cards in the 
workstation program package: 


e 3270 PC keyboard Quick Reference 
e Enhanced PC keyboard Quick Reference 
e AT and XT keyboard Quick Reference 


— 3270 Workstation Program Keyboard Templates 


The keyboard templates provided in the package assist you in using 
the workstation program functions on your particular keyboard. 
There are three templates in the package: 


e Enhanced PC keyboard template 
e AT keyboard template 
e XT keyboard template 


— Online tutorial diskette (Helper) 


This diskette contains introductory information and practice 
exercises to help in learning to use the 3270 Workstation Program. 


3270 PC High Level Language Application Programming Interface 
(HLLAPT)? 


The diskette and book that comes in this package make it possible for 
you to write application programs in BASIC, Pascal, or COBOL 
languages to use the API functions provided with the 3270 Workstation 
Program. 


The IBM Programmer’s Guide to the Server-Requester Programming 
Interface for the IBM Personal Computer and the IBM 3270 PC? 


This book explains how to write PC applications that request services 
from an application at an IBM System/370 type host system. In this 
relationship, the PC application is called the requester and the host 
application is called the server. This book also contains the return 
codes that are generated at the work station if problems occur in 
transmitting requests or replies. 


Contact your local IBM sales representative for information on how to obtain 
copies of these books. 


For information on IBM Personal Computer DOS, refer to the DOS manuals 
that were shipped with the version of DOS you are using. 


For information on IBM Personal Computer assembler language, use this 
manual: 


e IBM Personal Computer Language Series: Macro Assembler® 


Provides a reference for experienced assembler language programmers 
who use the IBM Personal Computer Macro assembler. Specific 
information is provided on how to use the Macro assembler, 
cross-reference facilities, pseudo-operations, and machine instructions. 
(Includes diskette.) 


For information on the IBM 3270 data stream, use this manual: 


e IBM 3270 Information Display System: Data Stream Programmer’s 
Reference? 


Provides information for programmers who need to know what is 


involved in using the 3270 data stream to produce panels or information 
at displays and printers. 


3 Contact your local IBM sales representative for information on how to obtain 
copies of these books. 
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Part 1. Introduction to the API 


The chapters in Part 1 introduce the Application Program Interface (API) 
and the two types of services you can use: 


e Application program services that most application programs will use. 
Described also are some supervisor services that directly support the 
application program services. 


e Those supervisor services that allow application programs to run 
together under the multitasking capabilities of the workstation 
program. 


The chapters in this part are: 


e Chapter 1, “Functions the API Provides,” which contains an overview 
of the API services and how you can use them. 


e Chapter 2, “Programming Considerations,” which introduces system 


information files, describes program information files, and provides tips 
and guidelines for coding programs. 
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Overview of API Services 


Overview of API Services 


The Application Program Interface (API) is just what the name implies: an 
interface between an application program and the IBM 3270 Workstation 
Program. Your application program requests services from the workstation 
program using the API. The kinds of services that your application can 
request are grouped into two categories: 


e Application program services 
e Supervisor services. 


The application program services are services that most application 
programs will use. The supervisor services are services that provide 
support for applications that use the multitasking capabilities of the IBM 
workstation program. 


Service requests to the workstation program are generated by your 
application program. The supervisor processes the requests or routes the 
request to the appropriate API service. 


Figure 1-1 illustrates the flow of a request from an application program. 
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Figure 1-1. Overview of the Application Program Interface 
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Terms You Need to Know 


ASCII 


EGA 


environment 


stoppable environment 


nonstoppable 
environment 


Non-3270 PC Hardware 


ODSP 


presentation space 


session 


= 


Terms You Need to Know 


American National Standard Code for 
Information Interchange. ASCII/ASCII 
mnemonics can now be sent or received on the 
Read Input and Write Keystroke API. 


Enhanced Graphics Adapter. For more 
information, see the Technical Reference 
Options and Adapters manual. 


A contiguous area of storage and a collection 
of system resources that are managed by an 
operating system to allow a program or a 
system extension to run. A program or a 
system extension is said to “run in an 
environment.” 


A type of environment that is used for running 
DOS or personal computer application 
programs. Stoppable environments can be 
used for any program that can be removed 
from the system without causing other 
programs to fail. That is, programs running in 
stoppable environments must not offer services 
to programs running in other environments. 


A type of environment used to run 

system extensions. These system extensions 
offer services to programs running in other 
environments and need to be in the system at 
all times. 


IBM Personal Computer AT® and/or XT 
system units without the keyboard adapter and 
3270 PC display adapter cards installed. 


Outbound Data Stream Preprocessor. ODSP 
allows the preprocessing of a 3270 data stream, 
which can reduce the amount of traffic flowing 
through a network. 


An area of storage that represents a logical 
display. All IBM 3270 host sessions, IBM 
personal computer sessions, and notepad 
sessions have a presentation space. The data 
contained in a presentation space, or a portion 
of that data, is displayed on the screen when 
that session’s window is visible on the screen. 


A connection between your work station and a 
host computer, personal computer, or notepad. 
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Examples of Using the API 


system extension 


window 


XMA ecard 


Examples of Using the API 


Code that runs in a nonstoppable environment. 
It is loaded as part of the workstation program 
and starts running automatically when the 
workstation program is I[PLed. A system 
extension may offer services that other 
programs can use. 


The portion of the screen through which you 
view a session’s presentation space. A window 
can be the same size as your full IBM 3270 
Personal Computer screen or as small as one 
character. 


Expanded memory adapter card. The XMA 
card is a hardware option card that provides 
up to 2Mb of additional storage for as many as 
6 PC sessions. 


The Application Program Interface (API) allows an assembler-language 
application program in the personal computer session to use a powerful set 
of services from the workstation program. 


Using these services, the application program can: 


e Simplify setup and control of multiple host sessions 


e Use the work station control functions of the IBM 3270 Personal 


Computer 


e Enhance interaction between the operator and a host 


e Extend the workstation program through the use of system extensions. 


Simplifying Setup and Control of Multiple Host Sessions 


For example, your application program can display a list of screen profiles 
to the work station operator. When the operator chooses one of the screen 
profiles, the program can send the necessary logon commands to each of the 
host sessions defined in the profile. In this way, you can set up the work 
station for use and eliminate the need for the operator to remember the 


various logon procedures. 
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The Application Program Services 


Using the Work Station Control Functions of the IBM 3270 Personal 
Computer 


Your application program can size and move windows, change the 
foreground and background colors of windows, jump to other windows, 
enlarge and hide windows, or do any of the other functions that are 
available in work station control mode. 

For example, your application program can translate a single key typed by 
the operator into a series of work station control commands to set up the 


IBM 3270 Personal Computer for data entry into a particular window on the 
screen. 


Enhancing Interaction between the Operator and a Host 
For example, your application can log onto four host sessions and bring up 
a different application on each host. Your application can present the work 


station operator with a menu of functions to perform and then transform 
the operator’s choice into a command to the appropriate host application. 


Extending the Workstation Program through the Use of System Extensions 


You can write a system extension that is loaded with the workstation 
program when the system is [PLed. A system extension can perform 
services for other application programs that you write, and act as a 
resource manager to allocate and deallocate resources to those application 
programs. 


The Application Program Services 


The API provides the following kinds of application program services: 
e Session information services 

e Keyboard services 

e Window management services 

e Host interactive services 

e Presentation space services 

e 3270 keystroke emulation services 

e Copy services 


e Translate service 
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The Application Program Services 


e Operator information area services 


e Multiple DOS support services. 


Session Information Services 


Keyboard Services 


The session information services allow your application program to query 
the workstation program to find out what sessions are currently defined, 
attach and detach from these sessions, and query what the characteristics 
of these sessions are. 


The keyboard services allow your application program to read and write 
keystroke data from a specified session, to disable and enable operator 
input from the keyboard of a specified session, and to notify the 
workstation program of the status of your application program’s keystroke 
processing. 


Window Management Services 


The window management services allow your application program to use 
the functions of the work station control session of the IBM 3270 Personal 
Computer. Using these services, your application program can determine 
the current size, position, or color of a window, and change them if desired. 
You can jump to specified windows, enlarge or hide windows, or change to 
a different screen profile. You can add a window, delete a window, or clear 
the entire screen. 


Host Interactive Services 


The host interactive services allow communication between a personal 
computer application program and a host application program using the 
destination/origin structured field protocol. The host interactive services 
also allow a personal computer application program to be notified when a 
host presentation space or operator information area is updated. 


Presentation Space Services 
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The presentation space services allow your application program to create 
and delete personal computer presentation spaces, to display those personal 
computer presentation spaces, and to control the position of the cursor in 
those personal computer presentation spaces. 


The Supervisor Services 


3270 Keystroke Emulation Services 


The 3270 keystroke emulation services enable you to type into a personal 
computer presentation space as if it were a host presentation space. 


Copy Services 


The copy services allow your application program to copy data into a 
personal computer window, as well as copy data from one area of a personal 
computer window into another area within the same personal computer 
window. The copy services also allow copying of data from and to host and 
notepad sessions. 


Translate Service 


Data that is displayed in host and notepad presentation spaces is 
represented by numbers called host/notepad character codes. Data that is 
displayed in personal computer presentation spaces is represented by ASCII 
codes. The translate service allows your application program to translate 
the data in a buffer from one type of data representation to the other. 


Note: You cannot translate graphic characters or programmed symbol set 
characters. 


Operator Information Area Services 
The operator information area services allow your application program to 


determine the current status of a session as shown on the operator 
information area (OIA). 


The contents of the OIA can be determined by reading: 


e An image of the OIA 
e A bit string that represents a group of related OIA values. 


Multiple DOS Support Services 
The multiple DOS support services allow your application program to query 


the size in paragraphs of a specified environment, and to request DOS INT 
21H function calls asynchronously. 


The Supervisor Services 


The API provides the following kinds of supervisor services: 


e Supervisory object services 
e Request services 


e Task state modifier services 


Chapter 1. Functions the API Provides 1-7 


The Supervisor Services 


Semaphore management services 
Logical timer management services 
Fixed-length queue management services 


Interrupt handler management services 


Environment manager services. 


Supervisory Object Services 


The supervisory object services allow your application program to create 
gates and user exit tables, and create and delete tasks, components, 
semaphores, and fixed-length queues. The supervisory object services also 
allow your application program to obtain the numeric ID of a supervisory 

/ object by specifying its alphanumeric name, or obtain the alphanumeric 
name of the supervisory object by specifying its numeric ID. 


Request Services 
The request services allow tasks and components in your application 


program to request services of other tasks or components and respond to 
requests from other tasks. 


Task State Modifier Services 


The task state modifier services allow your application program to change 
the dispatch state or priority of a task. 


Semaphore Management Services 


The semaphore management services allow your application program to 
control the access to resources and the execution of nonreentrant code. 


Logical Timer Management Services 


The logical timer management services allow your application program to 
control time-dependent events through the use of logical timers. 


Fixed-Length Queue Management Services 


The fixed-length queue management services allow your application 
program to pass data to other tasks or components, and to receive data from 
other tasks or components, using the fixed-length queue as a “pipeline” for 
the data. 
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Using the API 


Interrupt Handler Management Services 


The interrupt handler management services allow environments to share 
the interrupt vector table on a cooperative basis. On hardware interrupts, 
a device handler in any environment can receive control. 


Environment Manager Services 


The environment manager services allow a system extension to act as a 
resource manager to control the allocation and deallocation of resources to 
application programs. An application program has the ability to control its 
own environment using the environment manager services. 


Using the Application Program Interface 


To use the API, your program must store the required values in the system 
registers. Services that need more information than can be contained in 
the system registers use a data area called a parameter list to contain the 
additional information. System registers ES and DI must point to the 
segment and offset addresses of the parameter list. To request an API 
service, your application must issue an INT ‘7A’ instruction to signal the 
workstation program that it has a request to process. 
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Using the API 


Using the API 
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System Information Files 


Introduction 


Many application programs written for the IBM PC assume that the PC is 
dedicated to running a single application program at a time. Without the 
workstation program, this assumption is valid, since DOS provides a single 
environment to run programs and does not provide multitasking facilities. 
Some of these application programs take advantage of facilities available in 
the PC that are not supported by DOS, or bypass the DOS facilities to run 
more efficiently. 


The Multi-DOS feature of the workstation program provides a set of 
environments in which personal computer application programs can run, 
and a set of supervisor services that allow you to write programs that take 
advantage of this multitasking capability. To preserve the integrity of 
application programs running at the same time, the workstation program 
uses program information files (PIFs) and system information files (SIFs) to 
keep track of the application programs and system extensions that are 
running in the system. 


System Information Files 


System information files are used by the workstation program to allocate 
system resources for system extensions as well as for PC applications. A 
system extension is a module that you code. It is loaded with, and runs as 
part of, the workstation program. System extensions must observe all the 
rules for well-behaved programs that are described in this chapter. To 
include a system extension in your system, you must answer some questions 
about that system extension during customization, and you must create a 
system information file for that system extension. Chapter 24, “Coding 
System Extensions,” describes system extensions and discusses things you 
need to know to create system information files. 


There are several different system information files, which serve different 
purposes. They are: 


e INDIBM1.SIF — A special system information file which must be on the 
IPL disk when you initialize the workstation program. It is created 
during customization. It tells the workstation program how many 
system resources to allocate for all the workstation program’s system 
extensions. 


e INDIBM2.SIF — A special system information file which must be on the 
IPL disk when you initialize the workstation program. It is shipped 
with the workstation program diskettes. It tells the workstation 
program how many system resources to allocate for use by programs 
running in the PC sessions. If you have configured for Multi-DOS, the 
workstation program will allocate this many system resources for each 
PC session. This SIF may be tuned by the user to increase system 
resources if the system runs short. 


Program Information Files 


e Individual SIFs — Every user system extension must have a system 
information file to tell the workstation program how many system 
resources to allocate for its use. See the IBM 3270 Workstation 
Program User’s Guide and Reference for more information on system 
information files. 


The rest of this chapter concentrates on program information files. 


Program Information Files 


Program information files are used by workstation programs configured for 
Multi-DOS to control the execution of personal computer application 
programs. The workstation program needs to know whether or not the 
application program observes the rules for well-behaved programs so that 
the program does not interfere with other application programs that may be 
running at the same time. 


To obtain optimum performance, any application that is written to use the 
API services should be well-behaved. If you have customized your system to 
include the Multi-DOS option, you should create a program information file 
to tell the workstation program that your application is well-behaved. 


Note: If you do not have a PIF, your application will be considered 
ill-behaved and may suspend when it is not active. 


There are different program information files which serve different 
purposes. They are: 


@ 3270PC.PIF — This “consolidated PIF” must be on the IPL disk when 
you initialize the workstation program. It is copied to the IPL disk as 
part of the customization procedure. It contains program information 
for many different programs, including the 3270 PC utilities. It is read 
at IPL time. It is not in the same format as an individual PIF, described 
below. Program information may be added to the consolidated PIF by 
using the INDSPIF utility. Refer to the IBM 8270 Workstation Program 
User’s Guide and Reference for more information about the consolidated 
PIF. 


e Individual PIFs — Every application COM or EXE file may have a 
corresponding PIF. An individual PIF may be created by either the 
INDSPIF utility or the TopView “Create Program Information” utility 
Gif you use TopView). The individual PIF's used by the 3270 workstation 
program are compatible with the individual PIFs used by TopView. 
However, TopView PIFs have a different format than 3270 PC PIFs and 
require that you identify the specific interrupts your program will take 
over, even if your program takes them over using DOS and BIOS. The 
workstation program, however, requires you to identify the interrupts 
your program takes over only if you do not use DOS and BIOS. This 
means that, if you use your TopView PIF, the workstation program will 
interpret your program as poorly behaved even if it is well-behaved. 

See the IBM 3270 Workstation Program User’s Guide and Reference for 
more information about PIF files. 
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Creating and Modifying PIFs 


All of these PIFs and SIFs may be created, read, and modified using the 
INDSPIF utility, except TV.PIF. 8 


When a PC application is run, the workstation program first searches to see 
if there was a record for it in the consolidated PIF (8270PC.PIF). Failing to 
find it there, it will look for an individual PIF. If that fails, the 
workstation program will assume that the answer is “yes” to all PIF 
questions and that vectors to be swapped are 00-FF. 


Since the consolidated PIF and all SIFs are read at IPL time, any changes 
in these files will not be reflected until the next IPL of the workstation 
program. A change in an individual PIF will take effect when that program 
is next loaded. 


Creating and Modifying Program Information Files 


(PIFs) 
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You use the INDSPIF utility to create and modify PIFs. The INDSPIF 
utility is provided on your workstation program diskettes. 


To use the INDSPIF utility, follow these steps: 
1. Determine the name of the EXE or COM file you will use. 


Note: If you use a BAT file to run an application, you must create a PIF 
for the EXE or COM file, not for the BAT file. 


2. Decide whether the module is a system extension or a personal 
computer application program. 


a. For system extensions, determine how many of each type of control 
block are needed for the system extension to run. 
b. For application programs, determine which options apply to the 


application. 


3. At the DOS prompt, enter the INDSPIF command by typing INDSPIF 
and then pressing the Enter key. 


4, On the home panel, you may enter the module name or the path name. 


a. To create a system information file, press PF2. 
b. To read an existing system information file, press PF3. 


To create a program information file, press PF4. 


Pp 


To read an existing program information file, press PF5. 


e. To read existing program information from the consolidated PIF 
(3270PC.PIF), press PF6. 


f. To delete existing program information from the consolidated PIF 
(8270PC.PIF), press PF7. 


Restrictions on Running under the Workstation Program 


Depending on your choice, you will see either the PIF or the SIF panel. 


Complete all items on the panel. When you are done, press PF3 to save 
the PIF or SIF on diskette, or press PF4 to save the program 
information into the consolidated PIF. 


You may then press either Home, to return to the Home panel, or Esc, 
to quit the INDSPIF utility; or you may change any information on the 
panel and save it again. 


Restrictions on Running under the Workstation Program 


A number of situations should be avoided if the application is to run on the 
3270 PC in a Multi-DOS environment. In general, anything that will cause 
a contention for nonshareable resources should be avoided. The most 
common example is reading or writing to fixed memory addresses. An 
application should only read or write to addresses within its own address 
space. If an application needs to interact with the hardware, it should do 
so by issuing BIOS function calls, DOS function calls, or 3270 PC API 
function calls. 


The following are not supported and will cause system failures: 


Programming the Intel 8259 Interrupt Controller chip. 
Taking over interrupts X‘50’ through X‘57’ or X‘7A’. 
Disabling interrupts for an extended period of time. 
Disabling Direct Memory Access (DMA). 


Jumping to hard-coded addresses in the BIOS. All BIOS calls should be 
made through the interrupt mechanism. 


Running two workstation program applications on the 8087 or 80287 
math co-processor. 


Running an application that installs an interrupt handler that changes 
its own stack and then enables interrupts. This will produce 
unpredictable results on systems with an XMA card installed unless you 
revise the INDIBM2.SIF file. See the IBM 3270 Workstation Program 
User’s Guide for more details about updating INDIBM2.SIF. 


Using application hardware interrupt handlers that modify the registers 
and then CALLFAR the CHAINON address. 


For Uni-DOS on non-3270 PC hardware, an application is assumed to be 
ill-behaved. The application will be suspended when: 


— It is not the top or active window 
— The WSCtr]! key is pressed. 
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Guidelines for Running under Multi-DOS 


Guidelines for Running under Multi-DOS 


Programs running with Multi-DOS should observe the following rules for 
optimum performance: 


The program should not write to storage reserved by BASIC. See the 
Technical Reference manual for the IBM PC/XT for these locations. 


Note: Since BASIC itself writes to these locations, programs written in 
BASIC violate this rule. 


The program should not write to the PC’s interrupt vector table. The 
DOS function calls or the supervisor interrupt handler management 
services should be used to set interrupt vectors. 


The program should not write to the display refresh buffer. The BIOS 
or DOS facilities should be used to write to the screen. 


The program should not reprogram the PC’s timer. On non-3270 PC 
hardware, reprogramming the PC’s timer will cause host communication 
failure. 


The program should not reprogram the PC’s speaker. 


The program should not communicate directly with the keyboard. The 
BIOS or DOS facilities should be used to read data from the keyboard. 


The program should not wait in an idle loop until keys are pressed. 


The program should not directly poll the Asynchronous 
Communications Adapter (ACA). Instead, you should write an interrupt 
handler to communicate with the ACA. 


The program should not use graphics modes. 
The program should not read from, or write to, the BIOS data areas. 


For non-3270 PC hardware (XT only), if an application is intercepting 
keystrokes from a PC session that is running an ill-behaved application 
which takes over interrupt vector X‘9’, the first PC session will not 
receive any keystrokes. It will work only if you are running a 
well-behaved application. 


ANSLSYS is not supported under Multi-DOS. 


Virtual Device Interface (VDI) is not supported under Multi-DOS. 


If your application program does not follow the rules listed above, the 
Multi-DOS management portion of the workstation program may take 
special action when the program is running. 
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How Multi-DOS Affects Program Performance 


How Multi-DOS Affects Application Program 


Performance 


Following is a list of the special actions the workstation program may take 
if your application program does not observe some of the rules described: 


If your application program issues a function call to DOS, this request 
is serialized. You may not be able to jump to another PC window until 
that request is completed. You can jump to a host or notepad window, 
however, as long as that window follows the PC window in an 
alphabetic sequence of short names. For instance, if you are issuing 
DOS function calls in a PC window with a short name of A, then the 
host or notepad window you want to jump to should have a short name 
of B. 


If the program writes to storage reserved by BASIC, the Multi-DOS 
manager saves an image of this storage before it runs the program. 
Each time the program is suspended or put into a wait state, the 
Multi-DOS manager saves the current contents of the storage and swaps 
them with the original image of storage. Before the program is allowed 
to run again, the Multi-DOS manager again swaps the original image of 
storage with the image that was saved when the program was 
suspended. : 


If the program writes to the PC’s interrupt vector table, the Multi-DOS 
manager saves an image of these vectors before it runs the program. 
Each time the program is suspended or put into a wait state, the 
Multi-DOS manager saves the current contents of the vectors and swaps 
them with the original contents of the vectors. Before the program is 
allowed to run again, the Multi-DOS manager again swaps the original 
contents of the vectors with the contents that were saved when the 
program was suspended. 


Note: The workstation program fails if any program urites directly to 
interrupt vector X‘7A’. 


If the program writes to the display refresh buffer on 3270 PC hardware, 
the Multi-DOS manager suspends the program any time you jump to 
another PC session. For non-3270 PC hardware, the Multi-DOS 
manager suspends the program when it is not in the active window. 


If the program reprograms the PC’s timer, the Multi-DOS manager 
suspends the program any time it is not in the active window. Jumping 
to another PC window causes the timer to be reset to its default value. 


Note: If you are on non-8270 PC hardware, you should not reprogram — 
the timer. 


If the program reprograms the PC’s interrupt controller, the system 
fails. 

If the program communicates directly with the keyboard (that is, it 
takes over interrupt X‘09’ and reads keyboard data directly), the 
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Using the Interrupt X‘10’ Function 


Multi-DOS manager suspends the program any time it is not in the 
active window. 


e Ifthe program uses graphics modes, the Multi-DOS manager on 3270 PC 
hardware suspends the program any time you jump to another PC 
session. For non-3270 PC hardware, the Multi-DOS manager suspends 
the program when it is not in the active window. Only one PC session 
at a time may use graphics. 


Using the Interrupt X‘10’ Function 


On the PC, there are three ways of doing text output to the display screen. 
You can use DOS function calls, use BIOS function calls, or write directly 
to the video refresh buffer. The last method is frequently the only method 
acceptable where performance is a consideration. Unfortunately, using this 
method causes your application to be suspended when it is not the active 
window, in order to support Multi-DOS applications. If you want to run 
only on the workstation program, there is an alternative. You can do your 
video output through the API. This restricts your application to the 3270 
PC. 


There is a way to achieve high-performance screen output on a normal PC 
or on a 3270 PC with Multi-DOS without incurring performance 
degradation. This also works under TopView. 


To get the address of your presentation space: 


1. Load ES:DI with the assumed address of the video buffer (B000:0000). 
2. Load AH with X‘FR’. 

3. Issue an interrupt X‘10’. 
4 


The address of your presentation space will be returned in ES:DI. You 
should do all your display output to the address returned. 


To display your data: 


1. Load ES:DI with the address of the first character in the buffer that has 
been modified since the last display request. 


2. Load CX with the number of sequential characters or attribute bytes 
that have been modified. 


3. Load AH with X‘FF’. 
4. Issue an interrupt X‘10’. 


5. Data at ES:DI for CX bytes will be displayed in your PC window. 


These two functions allow an application to run under TopView and 3270 
Workstation Program, as well as on a PC running DOS. 


Note: Version 3.0 of the control program and the workstation program do 
not support Top View. 
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Tips on Writing Applications to Run in Multi-DOS 


Multi-DOS provides you with some powerful tools. For example, an 
application may download data from a CICS system, format it, and send it 
in the form of keystrokes to a customer’s spreadsheet program. 


There are, however, a number of restrictions. These restrictions are 
required because of the nature of existing PC software, software that was 
written to run in a single-tasking environment. 


You should, for example, be aware that your application can be suspended 
when it is not the top window. This happens if your PIF has a “yes” for 
any question, if you have no PIF, or if another PC environment has a PIF 
that indicates that it swaps vectors in the range X‘00’ through X‘7F’. 


This can cause problems if, for example, you lock WSCTRL, jump to 
another PC session, jump back, and release the WSCTRL lock. If the other 
session swaps vectors in the range X‘00’ through X‘7F’, your program is 
suspended before it can jump back and release the lock. Since you are 
holding the lock, no keyboard activity can occur. Since you are suspended, 
you cannot release the lock. Since you are not the active session, you 
cannot be resumed. This situation, known as circular waiting, is a classic 
deadlock. It effectively requires the user to power off and re-IPL the system 
in order to regain control. 


There are two ways to solve this problem. The first is to use the Query PC 
Session PIF Information service to determine whether you will be 
suspended. If you will, then avoid the above sequence of calls. The second 
is to claim a code serialization semaphore, issue the calls with a wait type 
of “no wait,” and then release the semaphore. Since you will not be 
suspended while holding the semaphore, you will be able to issue the calls, 
release the semaphore, and survive. The calls will occur asynchronously. 


You must be extremely careful with code serialization semaphores, 
however. If you are holding a code serialization semaphore across any 
segment of code that could cause a wait condition (for example, claim 
semaphore, get keyboard input, do something, release semaphore), you 
could also create a deadlock. If, while you are holding the semaphore, the 
user presses the JUMP key, this could happen: 


e The system tries to suspend you. 


e Since you hold a code serialization semaphore, the system waits until 
you release it to suspend you. 


e You are waiting on keyboard input. 


e The user cannot enter data into your session, because you are not the 
active session. 


The result is as in the previous example, a circular-wait condition. The 
system is deadlocked, requiring a power off/on to restart. 
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Tips on Writing Applications to Run in Multi-DOS 


If you are writing programs that create tasks and then exit back to DOS, 
make sure that you use a Terminate But Stay Resident call. If you do not, 
then the space in which your task is running will be overlaid by the next 
application to run. 


When Personal Computer Sessions Will Be Suspended 
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The following grid indicates when a personal computer session is 
suspended. The foreground task is never suspended. Those boxes marked 
with an “X” indicate when the background session(s) is suspended. 


The background session is: 


Well- Moderately Poorly 
The foreground session is: behaved well-behaved behaved 
Well-behaved 
Moderately well-behaved 
Poorly behaved 
Definitions: 


Foreground: If the active window (that is, the one with double borders) is a 
PC window, then it is the foreground session. If a non-PC window (host or 
notepad) is active, then the foreground session depends on the type of 
hardware you are using: 


e 3270 PC hardware: The PC window that was most recently active is 
considered the foreground session. 


e Non-3270 PC hardware: No PC window is considered to be the 
foreground session. All PC windows are background sessions and will 


be suspended if they either write directly to the screen or are poorly 
behaved. 


Background: Any window that is not the foreground window. 


Well-behaved: A personal computer session running a program that has a 
PIF in which every answer was “no”; that is, the personal computer 
application does nothing bad. This might also be a personal computer 
session that is running COMMAND.COM (for example, doing a DIR). 


Moderately well-behaved: A personal computer session running a program 
that has a PIF in which any answer was “yes,” but for which the space for 
“vectors swapped” did not include vectors in the range X‘00’ through X‘7F’. 


Poorly behaved: A personal computer session running a program that has 
no PIF, or for which the space for “vectors swapped” did include vectors in 
the range X‘00’ through X‘7F’. 


Non-3270 PC Hardware Restrictions 


Notes: 


dL 


If any program terminates and stays resident, then the workstation 
program treats that personal computer session as though the program 
were still running (that is, the program’s PIF remains in effect when 
determining whether to suspend the session). For example, suppose a 
program takes over an interrupt in the range of X‘80’ through X‘FF’, then 
terminates and stays resident. If another program is loaded, that 
program is still suspended when it is not in the foreground window. 
When the session is rebooted, the session is considered well-behaved 
again. 


If a program loads and runs another program using DOS function X‘4B’, 
the program that was loaded inherits the PIF characteristics of the 
loading program (for example, menu programs). 


Non-3270 PC Hardware Restrictions 


The following restrictions apply to non-8270 PC hardware (XT and AT). 
Failure to follow these guidelines on the use of non-3270 PC hardware could 
result in system failure. 


An application is assumed to be ill-behaved when running in Uni-DOS 
on non-3270 PC hardware. 


An ill-behaved application will be suspended when: 


— It is not the top or active window 
— The WSCTRL key is pressed 


— It uses the Input Control API to connect to the WSCTRL keyboard. 
(Note that this will affect all applications that will attempt to send 
Jump, ChgSc, and Enlarge keystrokes, as well as any other 
keystrokes that perform functions while in WSCTRL.) 


— On IPL if your PC session is not in the top window. Any program 
you start in your PC window will not be completed until you make 
it the active session (for example, your AUTOEXEC.BAT file). 


Ill-behaved applications will run only in an active session. If an 
ill-behaved application exits and stays resident in the active session, 
then any other application you run in that session will be seen as 
ill-behaved and will never run in the background. 


On non-3270 PC hardware, ill-behaved applications will be displayed 
full-screen when they are made active, even if they are sized. Even if 
you sized your windows using the API, they may be forced to full-screen 
and appear enlarged when active under the following conditions: 


— Your application uses graphics mode 


— Your application uses 40-column mode 
— Your application writes directly to the screen 
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Non-3270 PC Hardware Restrictions 


— Your application runs in Uni-DOS. 


e When an ill-behaved application uses the work station contro] API, the 
redraw screen and redraw window functions will not affect what is seen 
on the screen. Any changes made while the application is connected to 
the API will not be seen on the screen until the application disconnects 
from the API. 


e When using work station control API, the WS Ctrl OIA will not be 
displayed under the following conditions: 


~— Your application uses graphics mode 

— Your application uses 40-column mode 

— Your application writes directly to the screen 
- Your application runs in Uni-DOS. 


e If you are running an ill-behaved application in a PC session, the shift 
state of that session may not remain as you originally set it after 
jumping to other windows and back again. For instance, if you have set 
Caps Lock on in this PC session and jump to another window, your 
session may be in lowercase mode when you jump back to that window. 
Also, applications that write directly to the display adapter registers 
may not be restored properly after jumping to another window and back 
again. 


e Input Control API is not supported for sessions running ill-behaved 
applications that read port 60 directly. 


e Do not run PC applications that reprogram the timer. This could cause 
host communication failure. 


e An ill-behaved application that receives keystrokes from any other 
session will not work, because the application will be suspended when it 
is not the active session, so the keystrokes that it would normally be 
receiving will be queued up until the application becomes active. An 
ill-behaved application that sends keystrokes will work as long as its 
session remains active. 


e Use the BIOS INT 10, “Set Color Palette” call, to change the palette 
colors. Otherwise, the colors will be changed in all sessions. 


e If you load an alternate character generator into one session, then all 
your sessions will use this alternate character set. 


Determining the Program Level 


Determining the Type of PC Your Application Program Is 


Running On 


An application may perform the following test to determine whether it is 
executing on a 3270 PC. 


1. Perform a function call (INT X‘10’) to the BIOS Video Routine with the 
following parameters: 


AH register = X‘30’ 
AL register = X‘00’ 
CX register = X‘00’ 
DX register = X‘00’ 


2. Ifthe CX and DX registers are still zero (0) on return, the machine is 
\ not a 3270 PC or a non-3270 PC with the 3270 Workstation Program 
_ loaded. If the CX and/or DX registers are not zero, the following test 
should be made to determine whether the machine is a 3270 PC ora 
non-3270 PC with the 3270 Workstation Program loaded: 


a. 


b. 


Read the byte at CX:DX +2. 


If the value of this byte is X‘FF’, the machine is a PC without the 
3270 Workstation Program loaded. If the value of this byte is not 
X‘FF’, the machine is a 3270 PC or a non-3270 PC with the 3270 
Workstation Program loaded. 


Determining the Level of the Control Program or the 
Workstation Program That Is Loaded 


If the machine is a 3270 PC or a non-3270 PC, an application may determine 
whether the 3270 PC Control Program or the 3270 Workstation Program is 
loaded in memory, and if so what level of the program is currently resident, 
by performing the following tests: 


If CX:DX is not zero and not X‘C040:0220’, read the two-byte location at 
address CX:DX + 8. 


1. Ifthe contents of the two-byte location at address CX:DX+8 are X‘0000’, 
the following test should be performed to determine whether a 
pre-Version 2.0 level of the contro] program is resident: 


a. 


b. 


Read the BIOS high memory limit at address X‘0413’. 


Read the 8 bytes of data located 36 bytes beyond the BIOS high 
memory word obtained above. 


In rare instances, BIOS isolates bad high memory locations by 


placing the high address limit below these locations. If the control 
program or the workstation program is not loaded in memory when 
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Determining the Program Level 
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this test is performed, the application may inadvertently address 
these bad memory locations, which will result in a parity error. 
This is a nonrecoverable condition. 


c. Ifthe data at this memory location is X‘2322272031AFA210’, then 
the control program or workstation program is resident in memory. 


d. Ifthe control program is resident, the application can determine 
whether Version 1.0/1.1 or Version 1.2/1.21/1.22 is resident as 
follows: 


1) Read the 8 bytes of data located 16 bytes beyond the BIOS high 
memory limit. 


2) If the data found at this location is X‘353636392D303032’, the 
resident control program is Version 1.2 or 1.21 or 1.22. 
Otherwise, the resident control program is Version 1.0 or 1.1. 


If the contents of the two-byte location at address CX:DX +8 are not 
zero (Control Program Version 2.0 and later or the workstation 
program), it contains the segment address (at offset zero) where the 
application will find a two-byte field containing the identifier of the 
control program or workstation program in hexadecimal notation (0200 
for Control Program 2.0, 0210 for Control Program 2.1, 0300 for Control 
Program 3.0, and 0400 for Workstation Program 1.0). Immediately 
following the identifier is a single byte indicating the specific control 
program or workstation program installed: 


a. X‘00’ - Standard Control Program or Workstation Program 
b. X‘O1’ to X‘FF’ - Reserved 
Following the identifier is a 27-byte field containing an ASCII text 


string that identifies the type of control program or workstation 
program installed (for example, “IBM 3270 PC CONTROL PROGRAM”). 


Part 2. Application Program Services 


This part contains information about application program services provided 
by the Application Programming Interface. 


Chapter 3, “Coding Supervisor Services,” describes the supervisor 
services that your application program needs to use the rest of the 
services described in this part of the manual. 


Chapter 4, “Coding Session Information Service Requests,” describes 
the session information services that your application program can use. 


Chapter 5, “Coding Keyboard Service Requests,” describes the 
keyboard services that your application program can use. 


Chapter 6, “Coding Window Management Service Requests,” describes 
the window management services that your application program can 
use. 


Chapter 7, “Coding Host Interactive Service Requests,” describes the 
host interactive services that your application program can use. 


Chapter 8, “Coding Presentation Space Service Requests,” describes 
the presentation space services that your application program can use. 


Chapter 9, “Coding 3270 Keystroke Emulation Service Requests,” 
describes the keystroke emulator services that your application 
program can use. 


Chapter 10, “Coding Copy Service Requests,” describes the copy 
services that your application program can use. 


Chapter 11, “Coding Translate Service Requests,” describes the 
translate service that your application program can use. 


Chapter 12, “Coding Operator Information Area Service Requests,” 
describes the operator information area services that your application 
program can use. 


Chapter 13, “Coding Multi-DOS Support Service Requests,” describes 
the multiple DOS support services that your application program can 
use to query the size in paragraphs of a specified environment, and to 
request DOS INT 21H function calls asynchronously. 


Part 2. Application Program Services 


Conventions Used in the API Service Descriptions 


The following conventions are used in the descriptions of the API services: 


e Hexadecimal numbers are represented in the notation X‘nn’ for byte 
values and X‘nnnn’ for word values. 


e Offsets into data structures used by the API services are given as 
decimal numbers. 


e Bits within a byte are numbered with the high-order (leftmost) bit as bit 
0 and the low-order (rightmost) bit as bit 7, as follows: 


This order of bit numbering follows the IBM 360/370 convention and is the 
reverse of the Intel 8088 bit-numbering convention. 
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Introduction 


Introduction 


This chapter describes how to code requests for supervisor services provided 
by the API that are needed for the rest of the application program services 
described in this part of the manual. These supervisor services are a small 
subset of the supervisor services that are described in Part 3. 


You use the services in this chapter to obtain the gate name for the 
services your application program will use, to obtain the results of services 
that you have requested asynchronously, and to create, obtain data from, 
and delete fixed-length queues. 


Obtaining the Gate Name for the Services Your Application Program Will 


Use 


A gate is a grouping of services (or requests, as is the case with the 
multiple DOS support services) that perform a common function. Each gate 
is assigned a name when the gate is created. The workstation program 
provides the following groups of services/requests, or gates: 


Services or Requests Gate Name 


Session information services SESSMGR 
Keyboard services KEYBOARD 
Window management services WSCTRL 
Host interactive services MFIC 
Presentation space services PCPSM 
3270 keystroke emulation services 3270EML 
Copy services COPY 
Translate service XLATE 
Operator information area services OIAM 
Multiple DOS support services 

Query environment size INDJQRY 

Asynchronous DOS function INDJASY 

Get storage MEMORY 


Each group of services is identified to the workstation program by a 16-bit 
number, called the gate ID. Before your application program can use any of 
the services in a particular gate, you must obtain the gate ID that the 
workstation program assigns to the gate. You do this by requesting the 
Name Resolution service, specifying an alphanumeric gate name on the 
request. The workstation program returns the gate ID to your application 
program. You should save the gate ID in a variable, because you must 
provide it as input when you request any of the services in the gate. 


Introduction 


Obtaining the Results of Services You Have Requested Asynchronously 


Most of the application program interface services described in this part of 
the manual are processed synchronously by the workstation program. That 
is, when control is returned to your application program, the registers and 
the parameter list contain the values assigned to them on request 
completion. However, you can specify asynchronous processing of the 
following services: 


Keyboard service X‘04’: Write Keystroke 

Host interactive service X‘01’: Connect to Host Session 
Host interactive service X‘02’: Disconnect from Host Session 
Host interactive service X‘03’: Read Structured Field 

Host interactive service X‘04’: Write Structured Field 

Host interactive service X‘05’: Define Buffer 


When you specify asynchronous processing of these requests, control can be 
returned to your application program before the workstation program has 
completed the request. You must use the Get Request Completion service 
to obtain the values in the parameter list when the request is completed. 


You can also use the Get Request Completion service for request processing 
of task or components. Request processing is described in Part 3. 


Creating Fixed-Length Queue Entries 


For some of the application program interfaces, your application program 
must create a fixed-length queue. 


You create a fixed-length queue by requesting the Create Fixed-Length 
Queue Entry service. The workstation program uses fixed-length queues to 
notify your application program about events that have occurred and that 
affect the operation of your program, and also to pass keystrokes that were 
typed on the keyboard to your application program for processing. 


The space for the fixed-length queue must reside in your application 
program’s program space. The first 10 bytes of the queue are reserved for 
use by the workstation program. 


You can write code that uses fixed-length queues to pass data between 
programs running in the 3270 Personal Computer. The services that you 
use to do this are described in Part 3. 


Obtaining Data from a Fixed-Length Queue 


As described above, the workstation program uses fixed-length queues to 
notify your application program about events that have occurred and that 
affect the operation of your program. You obtain the data on a fixed-length 
queue by requesting the Dequeue Data service. The Dequeue Data service 
returns the specified number of bytes of information to your application 
program. 
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Introduction 


You can write code that uses fixed-length queues to pass data between 
programs running in the 3270 Personal Computer. The services that you 
use to do this are described in Part 3. 


Deleting Fixed-Length Queues 


When your application program no longer needs a fixed-length queue, it 
must tell the workstation program that the entry it has created for the 
fixed-length queue is no longer needed. You tell the workstation program 
to delete its entry for a fixed-length queue by requesting the Delete Entry 
service. 


The Delete Entry service can also be used to tell the workstation program 
to delete its entries for other supervisory objects. Information on these 
other supervisory objects is in Part 3. 


Note that the workstation program will not allow you to delete objects on 
which requests are still pending. For example, if a task has done a dequeue 
with a “wait for data” option set, the queue it is waiting on cannot be 
deleted until that request has been satisfied (that is, data is enqueued to 
that queue and returned to the dequeueing task). 


The supervisor services that you will need to code requests for the rest of 
the services in this part of the manual are: 


e Name Resolution: Use this service to resolve the application 
interface gate name to its numeric gate ID. 


e Get Request Completion: Use this service to obtain the results of 
services requested asynchronously. 


e Create Fixed-Length Queue Entry: Use this service to create an 
entry in the SVC table for a fixed-length queue. 


e Dequeue Data: Use this service to dequeue data from the specified 
fixed-length queue. 


e Delete Entry: Use this service to delete the entry in the SVC table for 
the specified fixed-length queue. 


Requesting the Supervisor Services 
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To request any of the supervisor services, load the registers and the 
parameter list with the proper values, and use the INT 7AH instruction to 
signal the workstation program that it has a request to process. 


Name Resolution 


Supervisor Service X‘81’: Name Resolution 


Use this service to resolve the application interface gate name to its 
numeric gate ID. You can also use this service for name resolution of other 
supervisory objects. Refer to Chapter 15, “Coding Supervisory Object 
Services,” for information about the additional uses of the Name Resolution 


service. 
Register Values 
On Request On Completion 
AH = X‘8l’ BH = X‘07’ 
ES = Segment address of the parameter list CH = X‘12’ or X‘13’ 
DI = Offset address of the parameter list CL = Return code 


DX = Gate ID 


The contents of registers 
AX, BL, ES, and DI are 
unpredictable. 


Register Definitions 
Request Registers: 
e The KS register contains the segment address of the parameter list. 
e The DI register contains the offset address of the parameter list. 
Completion Registers: 


e The DX register contains the resolved name, which is the numeric 
representation of the alphanumeric ASCII gate name. 


Parameter List Format 


Contents Contents 
Offset | Length on Request on Completion 


8 byte Unchanged 
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Name Resolution 


Parameter Definitions 
' Request Parameters: 


e The gate name must be ASCII characters, and must be padded to the 
right with blanks if it is less than eight characters long. The gate name 
to use for a group of services is described in the introduction to each 
chapter in this part of the manual. 


Return Codes 


The CH and CL registers contain a return code generated by the 
workstation program. System return codes use a function ID of X‘12’ or 
X‘13’ (found in the CH register). The error codes that can be received for 
this service are: 


Code Meaning 


X‘00’ Successful completion of the request 
X‘OF’ Invalid environment access 
X‘2E’ Name not found 


Coding Example 


PARAMETER LIST FOR NAME RESOLUTION 


=e Ne Ne 


SERVNAME DB 'KEYBOARD' 


; INITIALIZE REGISTERS FOR NAME RESOLUTION 


MOV AH,81H 
MOV DI,SEG SERVNAME 


AH = X'81' 

SEGMENT ADDRESS OF 

THE PARAMETER LIST 

ES = SEGMENT ADDRESS OF 
THE PARAMETER LIST 

DI = OFFSET ADDRESS OF 
THE PARAMETER LIST 


MOV ES,DI 


MOV DI,OFFSET SERVNAME 


=e Se Ne Ne NO Ne OS 


; SIGNAL WORKSTATION PROGRAM FOR NAME RESOLUTION SERVICE 


INT 7AH 


3-6 


Get Request Completion 


Supervisor Service X‘83°: Get Request Completion 


Use this service to obtain the results of the following services when they 


are 


Register Values 
On 


AH 
BL 


Set 


Register Definitions 


requested with asynchronous processing specified: 

Keyboard service X‘04’: Write Keystroke 

Host interactive service X‘01’: Connect to Host Session 
Host interactive service X‘02’: Disconnect from Host Session 
Host interactive service X‘03’: Read Structured Field 

Host interactive service X‘04’: Write Structured Field 


Host interactive service X‘05’: Define Buffer 


Request On Completion 
= X‘83’ AX = Request ID 
= X‘00’ or X*‘40’ BL = X‘00’ or X‘40’ 
CH = X‘12’ 
CL = Return code 
ES = Segment address of the parameter list 
DI = Offset address of the parameter list 


The contents of registers BH and DX are 
unpredictable. 


the BL register to: 


X‘00’ if you want to check whether results are available (asynchronous 
processing) 

X‘40’ if you want to wait until results are available (synchronous 
processing). 


Completion Registers: 


The AX register contains the request ID of the service whose results 
were obtained. This is the same value that was returned in the AX 
register of a previously requested service. You can determine which 
previously requested service the results are for by matching the request 
IDs. ; : 


The ES and DI registers are set to the segment and offset addresses of 
the service’s parameter list, which contains the results of the service. 
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Get Request Completion 


Parameter List Format 


Return Codes 


See the description of the requested service for the format of the parameter 
list. 


Code Meaning 


X‘00’ Successful completion of the request. 

X‘09’ No results are available. 

Additional return codes pertaining to the requested service may appear. 
Refer to the description of the requested service for a listing of the possible 
return codes. 


Coding Example 
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ue 8 Ne 


INITIALIZE REGISTERS FOR GET REQUEST COMPLETION 


MOV AH ,83H 
MOV BL,40H ; WAIT TYPE = COMPLETION QUEUE 


; SIGNAL WORKSTATION PROGRAM FOR GET REQUEST COMPLETION SERVICE 
INT 7AH 


Create Fixed-Length Queue Entry 


Supervisor Service X‘04’: Create Fixed-Length Queue 


Entry 


Use this service to create an entry in the SVC table for a fixed-length 


queue. 
Register Values 

On Request On Completion 

AH = X‘04’ CH = X‘12’ or X‘13’ 

BL = 0 = noname/ 1 = name CL = Return code 

CX = Queue length DX = Queue ID 

ES = Segment address of the parameter list 

DI = Offset address of the parameter list The contents of registers 
AX, BX, ES, and DI are 
unpredictable. 


Register Definitions 


Request Registers: 


The BL register indicates whether the queue has a name associated 
with it. 


Possible values for the BL register are : 


Q = the queue has no name 
1 = the queue’s name is in the parameter list 


The CX register contains the number of bytes your application program 
has reserved for the fixed-length queue. The queue must be greater 
than 10 bytes long, because the first 10 bytes of the queue are reserved 
for use by the workstation program. 


The ES register contains the segment address of the parameter list. 


The DI register contains the offset address of the parameter list. 


Completion Registers: 


The DX register contains the ID of the fixed-length queue. 
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Create Fixed-Length Queue Entry 


Parameter List Format 


Contents Contents 
Offset | Length on Request on Completion 


8 bytes Unchanged 


Parameter Definitions 


Return Codes 


Usage Notes 


1 word Offset address of the Unchanged 
queue 

1 word Segment address of Unchanged 
the queue 


Request Parameters: 


e The queue name is an optional parameter and is needed only if the BL 
register is set to 1 on request. The queue name can be a maximum of 
eight ASCII characters and should be padded to the right with blanks if 
necessary. 


The CH and CL registers contain a return code generated by the 
workstation program. System return codes use a function ID of X‘12’ or 
X‘13’ (found in the CH register). The error codes that can be received for 
this service are: 


Code 


X‘00’ 
X‘01’ 
X ‘02? 
X03’ 
X ‘41’ 


Meaning 


Successful completion of the request. 
Queue name already exists. 

SVC table full. 

Name table full. 

Invalid queue length. 


e The fixed-length queue resides in the requester’s environment. 
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Create Fixed-Length Queue Entry 


Coding Example 


. 
f 


; DEFINE PARAMETER LIST FOR CREATE QUEUE 
COQOFFS DW 


0 
COSEGM DW 0 
COONAME DB 8 


; INITIALIZE FIRST 2 ENTRIES OF PARAMETER LIST 


MOV CQQOFFS,OFFSET Q ; OFFSET OF QUEUE 
MOV  CQSEGM,SEG Q ; SEGMENT OF QUEUE 


; THE USER HAS A QUEUE NAME 


MOV BL,O1H INDICATE A QNAME IS SPECIFIED 


CLD ; BEGIN MOVING QNAME TO THE PARAM LIST 
MOV CX,4 ; QNAME IS FOUR WORDS LONG 

MOV SI,OFFSET QNAME ; SOURCE OFFSET OF QUEUE 

MOV DI,OFFSET CQQNAME;DESTINATION OFFSET IS CQQNAME 

REP MOVSW ; MOVE QNAME TO PARAMETER LIST 


; INITIALIZE REGISTERS FOR CREATE QUEUE 


MOV AH,04H 

MOV CX,50 CX = NUMBER OF BYTES FOR QUEUE 
MOV DI,SEG CQQOFFS  ; ADDRESSABILITY TO 

MOV ES,DI ; PARAMETER LIST 

MOV DI,OFFSET CQQOFFS; USING ES:DI 


° 
f 
° 
i 


+ SIGNAL WORKSTATION PROGRAM FOR CREATE QUEUE SERVICE 


INT 7AH 


Chapter 3. Coding Supervisor Services 3-11 


Dequeue Data 


Supervisor Service X‘13’: Dequeue Data 


Use this service to dequeue data from the specified fixed-length queue. 


Register Values 


On Request On Completion 

AH = X‘13’ CH = X‘12’ or X‘13’ 

BL = Wait type CL = Return code 

CX = Number of bytes DX = Number of bytes 

DX = Fixed-length queue ID 

ES = Segment address of data The contents of registers 

DI = Offset address of data AX, BX, ES, and DI are 
unpredictable. 


Register Definitions 
Request Registers: 


e The BL register specifies the type of wait state your application 
program will go into until the request is completed. The type of wait is 
specified through a bit mask. When more than one type of wait is 
specified, the wait state ends when any one of the conditions is 
satisfied. The bits in the wait type are as follows: 


aie Fae ee ee Fe ee ee ee 
Request| Comp | Comp | Sema- | Timer | Signal | Data | Reserved 
queue | queue | signal | phore 

— If bit 0 is set to 1, your application program will wait until a request 


queue element is in its request queue. If an RQE is already in its 
request queue, the application stays dispatchable. 


— If bit 1 is set to 1, your application program will wait until a request 
queue element is in its completion queue. If an RQE is already in its 
completion queue, the application stays dispatchable. 


— If bit 2 is set to 1, your application program will wait until it receives 
a ‘completion’ signal. 


~— If bit 3 is set to 1, your application program will wait until it receives 
a ‘got semaphore’ signal. 
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Return Codes 


Dequeue Data 


— If bit 4 is set to 1, your application program will wait until it receives 
a ‘timer tick’ signal. 


— If bit 5 is set to 1, your application program will wait until it receives 
a ‘generic’ signal. 


— If bit 6 is set to 1, your application program will wait until it receives 
a ‘data available’ signal. 


— Bit 7 is reserved and must be set to 0. 


Note: A wait type of “no wait” is specified by setting the wait type to 
X ‘00’. 


e The CX register contains the number of bytes to be dequeued from the 
specified fixed-length queue. When you are dequeueing information that 
the workstation program has placed on a fixed-length queue, this number 
should be X‘04’. 


e The DX register contains the ID of the fixed-length queue. 


e The ES and DI registers point to the beginning of a data area provided by 
your application to contain the dequeued data. 


Completion Registers: 


e The BL register indicates the type of wait condition that was satisfied to 
return control to the requesting task. The return type is specified 
through a bit mask. The bits in the return type have the same meaning 
as the bits in the wait type. 


e The DX register contains the number of bytes remaining on the 
fixed-length queue. a 


The CH and CL registers contain a return code generated by the workstation 
program. System return codes use a function ID of X‘12’ or X‘13’ (found in 
the CH register). The error codes that can be received for this service are: 


Code Meaning 


X‘00’ Successful completion of the request. 
X‘05’ Invalid index specified. 

X‘09’ The fixed-length queue is empty. 

X‘13’ Number of bytes requested is too large. 
X‘37’ Not your turn to dequeue. 
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Dequeue Data 


Usage Notes 


Coding Example 
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. 
’ 


° 
, 


DATAAREA DB 4 DUP(0O) 


, 


DATA AREA FOR 


Programs running in stoppable environments cannot dequeue data from 
fixed-length queues in other stoppable environments. 


If you want to get control back as soon as data appears on your queue, 
use a wait type of “wait for data available.” 


If two or more tasks request the Dequeue Data service for the same 
fixed-length queue, the supervisor processes the requests in first-in 
first-out (FIFO) order. 


If you use a wait type other than “wait for data available,” and another 
request for data from the queue was received before your request, you 
will receive a return code indicating that it is not your turn to dequeue. 


DEQUEUE 


DATA AREA TO RECEIVE 4 BYTES FROM THE 
DEQUEUE 


se Ne 


INITIALIZE REGISTERS FOR DEQUEUE 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


AH, 13H 

BL,02H ; WAIT UNTIL INFORMATION IS AVAILABLE 
CX ,0004H ; DEQUEUE 4 BYTES 

DX , QUEUEID ; FIXED-LENGTH QUEUE ID IN DX 

DI,SEG DQSESSID ; SEGMENT ADDRESS OF DATA AREA IN ES 
ES,DI 


DI,OFFSET DQSESSID ; OFFSET ADDRESS OF DATA AREA IN DI 


SIGNAL WORKSTATION PROGRAM FOR DEQUEUE SERVICE 


INT 


7AH 


Delete Entry 


Supervisor Service X‘06’: Delete Entry 


Use this service to delete the entry in the SVC table representing the 
specified fixed-length queue. 


Register Values 


On Request On Completion 
AH = X‘06’ CH = X‘12’ or X‘13’ 
DX = Fixed-length queue ID CL = Return code 


The contents of registers AX, BX, 
DX, ES, and DI are unpredictable. 


Register Definitions 
Request Registers: 


e The DX register contains the ID of the supervisory object to be deleted 
from the SVC table. 


Return Codes 
The CH and CL registers contain a return code generated by the workstation 
program. System return codes use a function ID of X‘12’ or X‘13’ (found in 


the CH register). The error codes that can be received for this service are: 


Code Meaning 


X‘00’ Successful completion of the request. 

X‘05’ Invalid supervisory object ID. 

X‘OF’ Specified object is in an inaccessible environment. 

X‘30’ Cannot delete a task, fixed-length queue, or semaphore that has 


pending requests. 
X‘31’ Cannot delete a task that has timers. 
X‘3F’ Cannot delete a service entry in a gate. 


Usage Notes 


e If requests are outstanding for the fixed-length queue entry, then the 
entry will not be removed and an error indicator will be returned. 


e An application program running in a stoppable environment can only 
delete entries in its own environment. 


e Part 3 of this manual describes additional supervisory objects the Delete 
Entry service can delete that you can create in application programs. 
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Delete Entry 


Coding Example 


; INITIALIZE REGISTERS FOR DELETE AN ENTRY REQUEST 
MOV AH,06H 
MOV DX,QUESID ; DX = FIXED LENGTH QUEUE ID 


; SIGNAL WORKSTATION PROGRAM FOR DELETE AN ENTRY SERVICE 


INT 7AH 
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This chapter describes how to code requests for the session information 
services provided by the API. 


The session information services allow your application program to query 
the workstation program to find out what sessions are currently defined, and 
what the characteristics of those sessions are. The session information 
services are: 


e Query Session ID Service: Use this service to obtain the ID of the 
session you specify. You can specify a particular session by its short or 
long name, or ask for the IDs of all sessions of a particular session type. 
The session types that are supported on the 3270 Personal Computer are: 


— The work station control session 

— Distributed function terminal (DFT) host session 
— Central unit terminal (CUT) host session 

— Notepad session 

— Personal computer session 


A session ID is required as input for most of the remaining API services. 
Your application program must request the Query Session ID service for 
all sessions it will be referencing in API service requests. Typically, 
obtaining the necessary session IDs is included in the initialization 
portion of an application program. 


e Query Session Parameters Service: Use this service to obtain the 
session characteristics of a particular session. The characteristics 
obtained by this service are: 


~ The session type 

— Whether the session has base or extended attribute support (host 
session only) 

~— Whether the session supports programmed symbols (host session 
only) 

— The number of rows and columns in the session’s presentation space 

— The segment and offset address of the session’s presentation space 


e Attach and Detach Session ID Services: Use these services to 
attach to and detach from a session. These services should be used by 
system extensions that provide some service to a session. Attaching to 
the session assures that the session will not be deleted until you detach 
from it. 


@e Query Windows in Environment Service: Use this service to obtain 
a list of the windows that are defined within a specified environment. 


Introduction 


e Query Environment of Window Service: Use this service to obtain 
the environment ID of a specified window. 


e Query PC Session PIF Information: Use this service to obtain a flag 
that indicates the answers to questions about the Program Information 
File. This is for the application program running in the specified 
personal computer session. 


e Query Base Window Service: Use this service to obtain the session 
ID and short name of the base window of a particular environment. The 
base window is the window that was defined at configuration time for the 
specified environment. You can use this service to obtain the session ID 
for the session your application program is currently running in. 


@e Query Session Cursor Service: Use this service to obtain the cursor 
type and the row and column addresses of the specified session’s cursor 
on the session’s presentation space. The possible cursor types are as 
follows: 
~ Underscore cursor (blinking or not blinking) 
An underscore cursor appears as: 

— Box cursor (blinking or not blinking) 
A box cursor appears as: @ 

— Inhibited cursor 
An inhibited cursor is not displayed. When the cursor position 
changes, the text in the window is not moved to keep the cursor 
inside the window borders. 

— Inhibited cursor with autoscroll 
An inhibited cursor with autoscroll is not displayed. When the 


cursor position changes, the text in the window is moved to keep the 
cursor inside the window borders. 


Requesting the Session Information Services 


To request any of the session information services, load the registers and the 
parameter list with the proper values, and use the INT 7AH instruction to 
signal the workstation program that it has a request to process. 


Note: Before your application can request the session information services, it 
must request the Name Resolution service, using ‘SESSMGR ’ as the 
gate name in the parameter list. (Remember that the gate name must be 
padded to the right with blanks if it is less than eight characters.) 
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Return Codes for the Session Information Services 


Each session information service has two return codes associated with it, a 

- system return code and a session management return code. Both types of 
return codes are 2-byte values made up of a function ID and an error number. 
The function ID indicates the portion of the workstation program in which 
the error occurred. The error number indicates the specific type of error 
that has occurred. An error number of X‘00’ always indicates a successful 
acceptance or completion of the request. 


e System return codes: 


After your application has requested a session information service, the 
CH and CL registers contain a return code generated by the request 
processing portion of the workstation program. The function ID is in the 
CH register, and the error number is in the CL register. System return 
codes use a function ID of X‘12’. The error codes that can appear are: 


Code Meaning 

X‘00’ ‘Request accepted. 

X ‘05’ Invalid index specified. 
X‘07’ Invalid reply specified. 

X ‘08’ Invalid wait type specified. 
X‘0B’ RQE pool depleted. 

X‘OF’ Invalid environment access. 
X ‘34’ Invalid gate entry. 


These system return codes apply to all session information services. 
e Session information services return codes: 


After a requested session information service is completed, bytes 0 and 1 
of the parameter list contain a return code generated by the session 
management portion of the workstation program. The function ID is in 
byte 1, and the error number is in byte 0. Session information return 
codes use a function ID of X‘6B’. The error numbers that can appear are 
specific to the service that was requested and are included in the 
descriptions of each service. 


See Appendix H, “Return Codes,” for more information. 
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Query Session ID 


Session Information Service X‘01’: Query Session ID 


Use this service to obtain the session ID of the session you specify. You can 
specify a session by its short or long name, or ask for the IDs of all sessions 
of a particular type. 


Register Values 


On Request On Completion 

AH = X‘09’ CH = X‘12’ 

AL = X0l’ CL = Return code 

BH = X‘80’ 

BL = X‘20’ The contents of registers 
CX = X‘0000’ AX, BX, DX, ES, and DI 
DX = Resolved value for SESSMGR are unpredictable. 

ES = Segment address of the parameter list 


DI Offset address of the parameter list 


Parameter List Format 


Fe a 
Offset Length | on Request on Completion 
[fo [1byte [Must be zero —‘([Return code 


1 word | Offset address of Unchanged 
name array 

1 word Segment address of Unchanged 
name array 


5 bytes Unchanged 


Parameter Definitions 
Request Parameters: 


e To obtain the session ID of a session whose short name you 
specify: 


— The option code must be X‘01’. 
~ The data code must be the 1-character (A—Z) ASCII short name of 
the session. 


The session long name is ignored. 
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Query Session ID 


e To obtain the session ID of a session whose long name you specify: 
— The option code must be X‘01’. 
— The data code must be X‘00’. 
— Bytes 8 through 15 must contain the long name of the session, padded 
to the right with blanks if it is less than eight characters long. 
e 


To obtain the session ID for all sessions of a specific session type: 


~ The option code must be X‘00’. 


— The data code must be: 
X‘01’ for a work station control session. 
X‘02’ for a DFT host session. 
X‘03’ for a CUT host session. 
X‘04’ for a notepad session. 
X‘05’ for a personal computer session. 


The session long name is ignored. 


Name Array Format 


Contents Contents 
Offset Length | on Request on Completion 


los A byte Name array length | Unchanged 


and so on for all possible matching sessions. 


* The format of the name array offsets 2 through 13 must be repeated for as many possible 
sessions as can match the Query Session ID service request. 
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Query Session ID 


Name Array Parameter Definitions 
Request Parameters: 


e The name array length is the number of bytes in the name array. The 
name array must be at least 14 bytes long and no greater than 170 bytes 
long. In addition, if you are coding this service to obtain the session ID 
for all sessions of a specific type, the name array must be large enough 
for all the possible matching sessions that can be returned for the session 
type. 


Completion Parameters: 


e The number of matching sessions contains the number of sessions that 
matched the request. 


e The session short name is the 1-character uppercase ASCII alphabetic 
name of the session (A through Z). 


e The session type is one of the following: 


— X‘01’ for a work station control session. 
— X‘02’ for a DFT host session. 

— X‘03’ for a CUT host session. 

— X‘04’ for a notepad session. 

— X‘05’ for a personal computer session. 


e The session ID is the ID that the workstation program uses to identify — 
the session. You use the session ID to specify this session in any 
following API service requests. 


e The session long name is the 8-character ASCII name assigned to the 


session when it was configured. The session long name is padded to the 
right with blanks if necessary. 
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Return Codes 
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e System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


e Session Information Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the session management portion of the workstation program. The 
function ID is in byte 1, and the error number is in byte 0. Session 
information services return codes use a function ID of X‘6B’. The error 
codes that can be received for this service are: 


Code 


X*‘00’ 
X‘03’ 
X‘09’ 
X‘0B’ 
X‘0C’ 
X‘0D’ 
XV’ 
X‘12? 
X‘13’ 


Meaning 


Successful completion. 

The specified long name is invalid. 

The session type is invalid. 

The specified short name is invalid. 

Byte 0 of the parameter list not zero on request. 

Invalid option code. 

No session has been configured for the specified session type. 
The name array length is invalid. 

The specified short name is not an uppercase ASCII alphabetic 
character. 


See Appendix H, “Return Codes,” for more information. 


Coding Example 


. 
’ 


; DEFINE PARAMETER LIST FOR QUERY SESSION ID 


QDRCODE 
QFXNID 
QDOPT 
QDDATA 
QDAOFF 
QDASEG 
ODLNAM 


DB O 
DB O 
DB 0 
DB 0O 
DW O 
DW O 
DB 8 

MOV 

MOV 

MOV 


DUP (' 


St a i) a ee) ee TY 


*) 


AX,SEG QDRCODE 
ES, AX 
DI,OFFSET QDRCODE 


. 
i 
. 
‘ 


° 
/ 


; INITIALIZE PARAMETER LIST FOR QUERY SESSION 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


AL,0O1H 

QDOPT, AL 

AL, 00H 

QDDATA, AL 

QDAOFF,OFFSET ARRAYNAME 
QDASEG,SEG ARRAYNAME 
QDRCODE , OOH 

QFXNID,OOH 


; THERE IS A LONG SESSION NAME 


CLD 
PUSH 
MOV 
MOV 
MOV 
MOV 
MOV 
REP 
POP 


; SET UP REGISTERS 


; SIGNAL WORKSTATION PROGRAM FOR QUERY 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


INT 


DS 

CX,4 

SI,OFFSET LONGNAME 
AX,SEG LONGNAME 
DS, AX 

DI,OFFSET QDLNAM 
MOVSW 

DS 


FOR QUERY SESSION ID 


AH,O9H 

AL,O1H 

BH, 80H 

BL,20H 

Cx, 00H 

DX, SESSMGR 
DI,OFFSET QDRCODE 


7AH 
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Oe et eT eT ee Te TY 


RESOLVED VALUE FOR 


Query Session ID 


RETURN CODE 

FUNCTION ID 

OPTION BYTE 

DATA BYTE 

NAMES ARRAY OFFSET 

NAMES ARRAY SEGMENT ADDRESS 
SESSION LONG NAME 


ADDRESSABILITY TO 
PARAMETER LIST 
USING ES:DI 


ID 


OBTAIN THE SESSION ID OF 
A LONG NAME SPECIFIED 


DATA BYTE 

ARRAY OFFSET 
ARRAY SEGMENT 
RETURN CODE = 
FUNCTION ID 


0 ON REQUEST 
0 ON REQUEST 


BEGIN MOVING NAME 

INTO PARAMETER LIST 
NAME IS FOUR WORDS LONG 
SOURCE OFFSET IN SI 


SOURCE SEGMENT IN DS 
DESTINATION OFFSET IN DI 
MOVE SESSION NAME TO 

TO PARAMETER LIST 


"SESSMGR' 


OFFSET ADDRESS OF 
PARAMETER LIST 


SESSION ID SERVICE 
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Query Session Parameters 


Session Information Service X‘02’: Query Session 


Parameters 


Register Values 


Use this service to obtain the session characteristics of the session you 
specify. 


On Request On Completion 

AH = X‘09’ CH = X‘12’ 

AL = X‘02’ CL = Return code 

BH = X‘80’ 

BL = X‘20’ The contents of registers 
CX = X‘0000’ AX, BX, DX, ES, and DI 
DX = Resolved value for SESSMGR are unpredictable. 


ES = Segment address of the parameter list 
DI = Offset address of the parameter list 


Parameter List Format 
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se a 
Offset | Length on Request on Completion 

fo [byte | Must be zero ——~«d Return code 
fea 


1 word Reserved Offset address of 
presentation space 

1 word Reserved Segment address of 
presentation space 


Query Session Parameters 


Parameter Definitions 


Request Parameters: 


The session ID is the ID of the session whose characteristics you are 
requesting. 


Completion Parameters: 


The session type byte is as follows: 


— X‘01’ for a work station control session. 
— X‘02’ for a DFT host session. 

— X‘03’ for a CUT host session. 

— X‘04’ for a notepad session. 

~— X‘05’ for a personal computer session. 


The bits in the session characteristics byte are as follows: 


Cane Fee Ss ee 
EAB | PSS 


—If bit 0 (EAB) = 0, the session has base attributes. 

—If bit 0 (EAB) = 1, the session has extended attributes. 

—If bit 1 (PSS) = 0, the session does not support programmed symbols. 
—If bit 1 (PSS) = 1, the session supports programmed symbols. 


“Rows” is the hexadecimal number of rows in the session’s presentation 
space. 


“Columns” is the hexadecimal number of columns in the session’s 
presentation space. 


The offset and segment addresses of the presentation space point to the 


session’s presentation space. See Appendix F for a discussion of 
presentation space considerations. 
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Return Codes 


Usage Notes 
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e System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


e Session Information Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the session management portion of the workstation program. The 
function ID is in byte 1, and the error number is in byte 0. Session 
information services return codes use a function ID of X‘6B’. The error 
codes that can be received for this service are: 


Code 


X‘00’ 
X‘02’ 
X‘06’ 
X‘0C’ 


Meaning 


Successful completion. 

Specified session ID is invalid. 

Specified session ID not in use. 

Byte 0 of the parameter list is not zero on request. 


See Appendix H, “Return Codes,” for more information. 


e The session ID required as input for this service can be obtained in the 


following ways: 


— By requesting the Query Session ID service 

— By requesting the Query Base Window service 

— Or, if you defined a presentation space with the Define Presentation 
Space service, the session ID would be returned 


Coding Example 


° 
‘ 


QPRETNCD 
QPFXNID 
QPSESSID 
QPRESERV 
QPSESTYP 
QPSESCHR 
QPROWS 
QPCOLS 
QPPSOFF 
QPPSSEG 


=e oe ON 


° 
’ 


DB 
DB 


_DB 


DB 
DB 
DB 
DB 


MOV 
MOV 
MOV 
MOV 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


OO00CO0O0000 


MOV | 


; PARAMETER LIST FOR QUERY SESSION 


QPRETNCD , OOH 


QPFXNID, 00H 
AL,SESSID 
QPSESSID, AL 


AH ,O9H 

AL ,O2H 
BH , 80H 

BL, 20H 

CX, OFFH 
DX,SESSMGR 


DI, SEG QPRETNCD 


ES,DI 


DI,OFFSET QPRETNCD 


St a at Bt Ml a! at eT Se eT 


° 
, 
° 
tA 
° 
a 


. 
f 
. 
a 
° 
f 
. 
f 


Query Session Parameters 


PARAMETERS SERVICE 


RETURN CODE 

FUNCTION NUMBER 

SESSION ID 

RESERVED 

SESSION TYPE 

SESSION CHARACTERISTICS 
NUMBER OF ROWS 

NUMBER OF COLUMNS 

OFFSET OF PRESENTATION SPACE 
SEGMENT OF PRESENTATION SPACE 


: INITIALIZE PARAMETER LIST FOR QUERY SESSION PARAMETERS SERVICE 


RETURN CODE MUST = O BEFORE REQUEST 
FUNCTION ID MUST = O BEFORE REQUEST 
SESSION ID INTO THE LIST 


INITIALIZE REGISTERS FOR QUERY SESSION PARAMETERS SERVICE 


RESOLVED VALUE FOR 'SESSMGR ' 

SEGMENT ADDRESS OF PARAMETER LIST 
IN ES 

OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR QUERY SESSION PARAMETERS SERVICE 


° 
t 


INT 


7AH 
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Session Information Service X‘04’: Detach Session ID 


Use this service to detach from a currently defined session. 


Register Values 


On Request On Completion 

AH = X‘09’ CH = X‘12’ 

AL = X‘04 CL = Return code 

BH = X‘80’ 

BL = X‘20’ The contents of registers 
CX = X‘00FF’ AX, BX, DX, ES, and DI 
DX = Resolved value for SESSMGR are unpredictable. 

ES = Segment address of the parameter list 


DI = Offset address of the parameter list 


Parameter List Format 


Function 1D O€6B) 
Unchanged 


Parameter Definitions 
Request Parameters: 


e The session ID is the ID of the session to detach from. 
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Return Codes 


Usage Notes 


Detach Session ID 


e System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


e Session Information Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the session management portion of the workstation program. The 
function ID is in byte 1, and the error number is in byte 0. Session 
information services return codes use a function ID of X‘6B’. The error 
codes that can be received for this service are: 


Code Meaning 


X‘00’ Successful completion. 

X‘02’ Specified session ID is invalid. 

X ‘06’ Specified session ID not in use. 

X‘0C’ Byte 0 of the parameter list is not zero on request. 
X‘14’ Cannot detach from the session now. 


See Appendix H, “Return Codes,” for more information. 


This service should be used only by a system extension that provides a 
service for some session. Attaching to a session ID by issuing an Attach 
Session ID service request guarantees that the session ID you are providing 
services for will not be deleted until you detach from it. However, it is 
possible for the fixed-length queue or presentation space associated with the 
session to be deleted. If a deletion of this type occurs before you issue a 
Detach Session ID request for the session, an appropriate error code will be 
issued when you request a service for the session. If this error occurs, you 
should request the Detach Session ID service for the session, to make the 
session ID available to some other system extension. 
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Coding Example 
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ry 
’ 


; PARAMETER LIST FOR DETACH SESSION ID 


DTRETNCD DB 
DTFXNID DB 
DTSESSID DB 
DTRSRVD DB 


oOo0°0 


° 
f 
° 
f 


. 
f 


RETURN CODE 
FUNCTION ID 
SESSION ID 


; INITIALIZE PARAMETER LIST FOR DETACH SESSION ID 


MOV 
MOV 
MOV 
MOV 


DTRETNCD , 00H 
DTFXNID,00H 
AL, SESSID 

DTSESSID,AL 


. 
t 
° 
/ 
/ 
. 
/ 


RETURN CODE MUST 
FUNCTION ID MUST 
SESSION ID IN 
PARAMETER LIST 


O BEFORE REQUEST 
O BEFORE REQUEST 


; INITIALIZE REGISTERS FOR DETACH SESSION ID 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


° 
f 


AH, 09H 

AL, 04H 

BH, 80H 

BL, 20H 

CX, OF FH 

DX,SESSMGR 

DI, SEG DTRETNCD 
ES,DI 

DI,OFFSET DTRETNCD 


. 
‘ 
. 
t 
f 
e 
f 


NAME RESOLUTION FOR SESSMGR 
SEGMENT ADDRESS OF PARAMETER LIST 
IN ES 

OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR DETACH SESSION ID SERVICE 


e 
, 


INT 


7AH 


Attach Session ID 


Session Information Service X‘05’: Attach Session ID 


Use this service to attach to a currently defined session. 


Register Values 


On Request On Completion 

AH = X‘09’ CH = X‘12’ 

AL = X‘05’ CL = Return code 

BH = X‘80’ 

BL = X‘20’ The contents of registers 
CX = X‘00FF’ AX, BX, DX, ES, and DI 
DX = Resolved value for SESSMGR are unpredictable. 

ES = Segment address of the parameter list 

DI = Offset address of the parameter list 


Parameter List Format 


om frags [Sta [Sas 
| Offset | Length on Request on Completion 

fo [1byte [Must be zero ‘(Return code 
Reserved Reserved 


Parameter Definitions 
Request Parameters: 


e The session ID is the ID of the session to attach to. 


Chapter 4. Coding Session Information Service Requests 4-17 


Attach Session ID 


Return Codes 


Usage Notes 
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e System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


e Session Information Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the session management portion of the workstation program. The 
function ID is in byte 1, and the error number is in byte 0. Session 
information services return codes use a function ID of X‘6B’. The error 
codes that can be received for this service are: 


Code 


X‘00’ 
X‘02’ 
X‘05’ 
X‘06’ 
X‘0C’ 


Meaning 


Successful completion. 

Specified session ID is invalid. 

Attachment limit exceeded. 

Specified session ID not in use. 

Byte 0 of the parameter list is not zero on request. 


See Appendix H, “Return Codes,” for more information. 


This service should only be used by a system extension that provides a 
service for some session. Attaching to a session ID guarantees that the 
session ID you are providing services for will not be deleted until you 
detach from it. However, it is possible for the fixed-length queue or 
presentation space associated with the session to be deleted. If a deletion of 
this type occurs before you issue a Detach Session ID request for the 
session, an appropriate error code will be issued when you request a service 
for the session. If this error occurs, you should request the Detach Session 
ID service for the session, to make the session ID available to some other 
system extension. 


Attach Session ID 


Coding Example 


° 
f 


; PARAMETER LIST FOR ATTACH SESSION ID 


; RETURN CODE 
; FUNCTION ID 
; SESSION ID 


ATRETNCD DB 
ATFXNID DB 
ATSESSID DB 
ATRSRVD DB 


oo0°0 


; INITIALIZE PARAMETER LIST FOR ATTACH SESSION ID 


RETURN CODE MUST 
FUNCTION ID MUST 
SESSION ID IN 
PARAMETER LIST 


0 BEFORE REQUEST 
O BEFORE REQUEST 


MOV ATRETNCD,OOH 
MOV ATFXNID, OOH 
MOV AL,SESSID 

MOV ATSESSID,AL 


ol 


=e Se ee Me 


; INITIALIZE REGISTERS FOR ATTACH SESSION ID 


MOV AH,O9H 

MOV AL,O5H 

MOV BH,80H 

MOV BL,20H 

MOV CX,OFFH 

MOV DX,SESSMGR ; NAME RESOLUTION FOR SESSMGR 

MOV DI, SEG ATRETNCD ; SEGMENT ADDRESS OF PARAMETER LIST 
MOV ES,DI ; IN ES 

MOV ODI,OFFSET ATRETNCD ; OFFSET OF PARAMETER LIST IN DI 


SIGNAL WORKSTATION PROGRAM FOR ATTACH SESSION ID SERVICE 


=e Ne Ne 


INT 7AH 
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Session Information Service X‘06’: Query Windows in 
Environment 
Use this service to obtain a list of the windows that are defined within a 
specified environment. The windows in the environment are listed by their 


short name. You can also use this service to obtain the ID of the currently 
active environment. 


Register Values 


On Request On Completion 

AH = X‘09’ CH = X‘12’ 

AL = X‘06’ CL = Return code 

BH = X‘80’ 

BL = X‘20’ The contents of registers 
CX = X‘O0OFF’ AX, BX, DX, ES, and DI 
DX = Resolved value for SESSMGR are unpredictable. 

ES = Segment address of the parameter list 


DI = Offset address of the parameter list 


Parameter List Format 


Contents Contents 
Offset | Length on Request on Completion 
fo [1tyte [Must be zero ‘[Return code 
Function ID 6B) 


2 1 byte Environment ID or Unchanged or 
: X‘00’ environment ID 
Number of windows 
| 
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Parameter Definitions 

Request Parameters: 

e The environment ID is the ID of the environment whose window short 
names you wish to obtain. If you want to obtain the ID of the currently 
active environment, specify X‘00’ in this field in the parameter list on 
request. 


Completion Parameters: 


e If you specified X‘00’ in byte 2 of the parameter list on request, the ID of 
the currently active environment is returned. 


e The number of windows is the number of windows defined to belong to 
the specified environment. 


e The window short name is the 1-character uppercase ASCII alphabetic 
name of each window that belongs to the environment. 


Return Codes 
e System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


e Session Information Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the session management portion of the workstation program. The 
function ID is in byte 1, and the error number is in byte 0. Session 
information services return codes use a function ID of X‘6B’. The error 
codes that can be received for this service are: 


Code Meaning 


X‘00’ Successful completion. 
X‘0A’ Invalid environment ID. 
X‘0C’ Byte 0 of the parameter list is not zero on request. 


See Appendix H, “Return Codes,” for more information. 


Usage Notes 


e You can use the Query Environment service to obtain the environment 
ID to use as input for this service. 
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Coding Example 
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° 
, 


e 
, 


PARAMETER LIST FOR QUERY WINDOWS 


, 

QOQRETNCD DB 
QQFXNID DB 
QOENVID DB 
QONUMWIN DB 
QOWNAMS DB 


° 
c 


° 
‘ 


, 


. 
, 


° 
, 


0 
0 
0 
0 


20 DUP(?) 


IN ENVIRONMENT 


~e Ne Se Ne Ne 


RETURN CODE 
FUNCTION ID 
ENVIRONMENT ID 
NUMBER OF WINDOWS 
WINDOW SHORT NAMES 


INITIALIZE PARAMETER LIST FOR QUERY WINDOWS IN ENVIRONMENT 


MOV 
MOV 
MOV 
MOV 


QQRETNCD , OOH 
QOFXNID, 00H 
AL,ENVID 
QQENVID, AL 


se Ne Ne Ne 


RETURN CODE MUST 
FUNCTION ID MUST 
ENVIRONMENT ID 

IN PARAMETER LIST 


0 BEFORE REQUEST 
0 BEFORE REQUEST 


INITIALIZE REGISTERS FOR QUERY WINDOWS IN ENVIRONMENT 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


AH, 09H 

AL, 06H 

BH, 80H 

BL, 20H 

CX, OFFH 

DX, SESSMGR 

DI, SEG QQRETNCD 
ES,DI 

DI,OFFSET QQRETNCD 


. 
f 
. 
r 
. 
Ld 
, 


NAME RESOLUTION FOR SESSMGR 
SEGMENT ADDRESS OF PARAMETER LIST 
IN ES 

OFFSET OF PARAMETER LIST IN DI 


SIGNAL WORKSTATION PROGRAM FOR QUERY WINDOWS IN ENVIRONMENT SERVICE; 


INT 


7AH 


Query Environment of Window 


Session Information Service X‘07’: Query Environment 
of Window | 


Use this service to obtain the environment ID of a specified window. 


Register Values 


On Request On Completion 

AH = X‘09’ CH = X‘12’ 

AL = X‘07’ CL = Return code 

BH = X‘80’ 

BL = X‘20’ The contents of registers 
CX = X‘00FF’ AX, BX, DX, ES, and DI 
DX = Resolved value for SESSMGR are unpredictable. 


ES = Segment address of the parameter list 
DI = Offset address of the parameter list 


Parameter List Format 


Offset | Length on Request on Completion 
[0 —s{ibyte | Mustbezero | Returncode 
[2 {ibyte | Window shortname [Unchanged 


Parameter Definitions 
Request Parameters: 


e The window short name is the ASCII short name of the window whose 
environment ID you are requesting. 


Completion Parameters: 


e The environment ID is the ID of the environment that owns the 
specified window. 
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Return Codes 
e System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


e Session Information Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the session management portion of the workstation program. The 
function ID is in byte 1, and the error number is in byte 0. Session 
information services return codes use a function ID of X‘6B’. The error 
codes that can be received for this service are: 


Code Meaning 


X‘00’ Successful completion. 

X ‘0B’ Specified short name is invalid. 

X‘0C’ Byte 0 of the parameter list not zero on request. 

X ‘13’ Specified short name is not an uppercase ASCII alphabetic 
character. 


See Appendix H, “Return Codes,” for more information. 


Usage Notes 
e The window name is either: 


- The short window name selected at customization time (which may 
be found using the Query Base Window service), or . 


— The window name specified on the Define Presentation Space 


service or returned by this service, if you allowed the system to 
select an available window name for you. 
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Query Environment of Window 


Coding Example 


° 
f 


; PARAMETER LIST FOR QUERY ENVIRONMENT OF WINDOW 


RETURN CODE 
FUNCTION ID 
WINDOW SHORT NAME 
ENVIRONMENT ID 


QIRETNCD DB 
QIFXNID DB 
QIWINDOW DB 
QIENVID DB 


O0O000 


; INITIALIZE PARAMETER LIST FOR QUERY ENVIRONMENT OF WINDOW 


RETURN CODE MUST = O BEFORE REQUEST 
FUNCTION ID MUST = O BEFORE REQUEST 
WINDOW SHORT NAME IN 

PARAMETER LIST 


MOV QIRETNCD,OOH 
MOV QIFXNID,OOH 

MOV AL,'P! 

MOV QIWINDOW,AL 


~e we Ne Ne 


; INITIALIZE REGISTERS FOR QUERY ENVIRONMENT OF WINDOW 


MOV AH , 09H 
MOV AL,O7H 
MOV BH, 80H 
MOV BL,20H 
MOV CX ,OFFH 
MOV DX,SESSMGR ; NAME RESOLUTION FOR SESSMGR 
MOV DI, SEG QIRETNCD ; SEGMENT ADDRESS OF PARAMETER LIST 
MOV ES,DI ; IN ES 
MOV DI,OFFSET QIRETNCD ; OFFSET OF PARAMETER LIST IN DI 
; SIGNAL WORKSTATION PROGRAM FOR QUERY ENVIRONMENT OF WINDOW SERVICE; 


INT 7AH 
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Session Information Service X‘08’: Query PC Session 
Program Information File (PIF) Information 


Use this service to obtain a flag that represents the PIF for the application 
program running in the specified personal computer session. 


Register Values 


On Request On Completion 

AH = X‘09’ CH = X‘12’ 

AL = X‘08’ CL = Return code 

BH = X‘80’ 

BL = X‘20’ The contents of registers 
CX = X‘00FF’ AX, BX, DX, ES, and DI 
DX = Resolved value for SESSMGR are unpredictable. 

ES = Segment address of the parameter list 

DI = Offset address of the parameter list 


Function ID (6B) 
Unchanged 
PC session flags 


Parameter Definitions 
Request Parameters:. 
e The session ID is the ID of the PC session being queried. 
Completion Parameters 
e The bits in the PC session flags indicate the answers to questions in the 
PIF for the application running in the specified session. 


Chapter 2, “Programming Considerations” contains information on 
creating PIFs and how they are used. 
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e The format of the PC session flags is as follows (remember that bit 0 is 
the high-order, leftmost, bit in the word and bit 15 is the low-order, 
rightmost, bit in the word): 


— Bit 0 = 1 means that the DISPLAY question was answered “yes.” 

— Bit 1 = 1 means that the INTERRUPT VECTORS swapped include 
vectors in the range X‘00’ through X‘7F’. 

— Bit 2 = 1 means that the INTERRUPT VECTORS swapped include 
vectors in the range X‘80’ through X‘FF’. 

— Bit 3 = 1 means that the TIMER question was answered “yes.” 

— Bit 4 = 1 means that the KEYBOARD question was answered “yes.” 

— Bit 5 is reserved. 

— Bit 6 is reserved. 

— Bit 7 is reserved. 

— Bit 8 = 1 means that the 8087 question was answered “yes.” 

— Bit 9 is reserved. 

— Bit 10 = 1 means that the FOREGROUND question was answered 
“yes.” 

— Bit 11 is reserved. 

— Bit 12 is reserved. 

— Bit 13 is reserved. 

— Bit 14 = 1 means that the MEMORY question was answered “yes.” 

— Bit 15 is reserved. 


For example, to test flag 1 to determine whether the session swaps 
interrupt vectors in the range X‘00’ through X‘7F’, you can code: 


MOV AX,SFLFLG ; LOAD REGISTER WITH FLAGS 
TEST AX,4000H ; BINARY ‘01000000 O0Q000000' 
JE FLAGSET ; TEST SUCCEEDED, TAKE JUMP 


FLAGSET: ; FLAG 1 IS SET 
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Return Codes 


Usage Notes 
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System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


Session Information Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the session management portion of the workstation program. The 
function ID is in byte 1, and the error number is in byte 0. Session 
information services return codes use a function ID of X‘6B’. The error 
codes that can be received for this service are: 


Code Meaning 


X‘00’ Successful completion. 

X ‘02’ Specified session ID is invalid. 

X‘06’ Specified session ID is not in use. 

X‘0C’ Byte 0 of the parameter list is not zero on request. 


See Appendix H, “Return Codes,” for more information. 


An application program can request this service for its own session or 
for any other PC session in the same environment or any other 
environment. 


The use of this service is helpful if, for example, an application program 
needs to know whether it will be suspended if it is not the foreground 
application. Using the information obtained by this service allows the 
application program to avoid situations such as jumping to another 
session, becoming suspended, and being unable either to jump back or 
to release a lock on the work station control session. A situation such 
as this will hang the workstation program. 


If you are running an application using this service in a system that is 
not configured for Multi-DOS, the flag byte returned will be 00. 


Query PC Session PIF Information 


Coding Example 


. 
’ 


; PARAMETER LIST FOR QUERY PC SESSION PIF INFORMATION 


SFLRCVAL DB 
SFLRCFNC DB 
SFLSID DB 
SFLFLG DW 


RETURN CODE 
FUNCTION ID 
SESSION ID 


oOo0°0 


INITIALIZE PARAMETER LIST FOR QUERY PC SESSION PIF INFORMATION 


=e Ne Ne 


MOV SFLRCVAL,OOH 
MOV SFLRCNFC,OOH 
MOV AL,SESSID 
MOV SFLSID,AL 


RETURN CODE MUST 
FUNCTION ID MUST 
SESSION ID IN 
PARAMETER LIST 


0 BEFORE REQUEST 
0 BEFORE REQUEST 


=e Ne Ne Ne 


INITIALIZE REGISTERS FOR QUERY PC SESSION PIF INFORMATION 


se tO Ne 


MOV AH,O9H 

MOV AL,O8H 

MOV BH,80H 

MOV BL,20H 

MOV CX, OFFH 

MOV DX,SESSMGR ; NAME RESOLUTION FOR SESSMGR 

MOV DI, SEG SFLRCVAL  ; SEGMENT ADDRESS OF PARAMETER LIST 
MOV ES,DI ; IN ES 

MOV DI,OFFSET SFLRCVAL ; OFFSET OF PARAMETER LIST IN DI 

; SIGNAL WORKSTATION PROGRAM FOR QUERY PC SESSION PIF INFORMATION SERVICE 


INT 7AH 
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Session Information Service X‘0A’: Query Base Window 


Use this service to obtain the session ID and short name of the base window 
of the specified environment. A base window is any window that was 
defined at configuration time or created using the INDSPLIT or 
INDMERGE commands. 


Register Values 


On Request On Completion 

AH = X‘09’ CH = X‘12’ 

AL = X‘0A’ CL = Return code 

BH = X‘80’ 

BL = X‘20’ The contents of registers 
CX = X‘0O0FF’ AX, BX, DX, ES, and DI 
DX = Resolved value for SESSMGR are unpredictable. 

ES = Segment address of the parameter list 


DI = Offset address of the parameter list 


Parameter List Format 


 — 
Offset | Length on Request on Completion 
[o_[ibyte | Must be zero —~(| Return code 
Function 1D 6B) 


1 byte Window short name 


1 byte 


Parameter Definitions 
Request Parameters: 
e The environment ID is the ID of the environment whose base window 
identity you are requesting. If this parameter is zero, the environment 
ID defaults to the current environment. 
Completion Parameters: 


@ The session ID is the ID of the session associated with the base window. 


e The window short name is the one-character uppercase ASCII name of 
the base window. 
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Return Codes 
e System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


e Session Information Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the session management portion of the workstation program. The 
function ID is in byte 1, and the error number is in byte 0. Session 
information services return codes use a function ID of X‘6B’. The error 
codes that can be received for this service are: 


Code Meaning 


X‘00’ Successful completion. 

X‘0A’ Invalid environment ID. 

X‘0C’ Byte 0 of the parameter list is not zero on request. 
X‘0E’ Base window is not found. 


See Appendix H, “Return Codes,” for more information. 


Usage Notes 
e Use this service to obtain the session ID of the window you are 


currently working in, if that window was not created using the Define 
Presentation Space service. 
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Coding Example 
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e 
‘ 


* 
f 


QSRETNCD DB 
QSFXNID DB 
QSENVID DB 
QSSESSID DB 
QSWINDOW DB 
QSRESERV DB 


, 


1 


° 
, 
° 
f 


° 
a 


oOO0O000 


=e “se Se Se SO NO 


PARAMETER LIST FOR QUERY BASE WINDOW 


RETURN CODE 
FUNCTION NUMBER 
ENVIRONMENT ID 
SESSION ID 
WINDOW SHORT NAME 
RESERVED 


INITIALIZE PARAMETER LIST FOR QUERY BASE WINDOW 


MOV 
MOV 
MOV 


QSRETNCD , OOH 
OSFXNID, OOH 
OSENVID,O 


° 
‘ 
° 
tA 


e 
’ 


RETURN CODE MUST QO BEFORE REQUEST 
FUNCTION ID MUST QO BEFORE REQUEST 
USE DEFAULT OF CURRENT ENVIRONMENT 


INITIALIZE REGISTERS FOR QUERY BASE WINDOW 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


AH, 09H 
AL, OAH 

BH , 80H 

BL, 20H 

CX, OFFH 

DX ,SESSMGR 

DI, SEG QSRETNCD 
ES ,DI 

DI,OFFSET QSRETNCD 


° 
, 
e 
t 
° 
f 
° 
J 


RESOLVED VALUE FOR 'SESSMGR ' 
SEGMENT ADDRESS OF PARAMETER LIST 
IN ES 

OFFSET OF PARAMETER LIST IN DI 


SIGNAL WORKSTATION PROGRAM FOR QUERY BASE WINDOW SERVICE 


INT 


7AH 


Query Session Cursor 


Session Information Service X‘0B’: Query Session Cursor 


Use this service to obtain the cursor type and the row and column 
addresses of the specified session’s cursor. 


Register Values 


On Request On Completion 

AH = X‘09’ CH = X‘12’ 

AL = X‘0B’ CL = Return code 

BH = X‘80’ 

BL = X‘20’ The contents of registers 
CX = X‘O0FF’ AX, BX, DX, ES, and DI 
DX = Resolved value for SESSMGR are unpredictable. 

ES Segment address of the parameter list 


DI Offset address of the parameter list 


Parameter List Format 


Pe a a 
Offset | Length on Request on Completion 
fo [1byte [Must be zero | Returneode ___— 


Reserved Column address 


Parameter Definitions 
Request Parameters: 


e The session ID is the ID of the session whose cursor information you 
are requesting. 
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Return Codes 
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Completion Parameters: 


The cursor type byte is as follows (where bit 0 is the high-order bit and 
bit 7 is the low-order bit): 


Reserved 

Reserved 

Reserved 

Inhibited cursor with autoscroll 
Reserved 

Inhibited cursor 

Blinking cursor 

Box cursor 


TS OR CO DS eH S&S 


The row address is the address in the session’s presentation space 
representing the cursor’s row position. Row addresses start with zero. 


The column address is the address in the session’s presentation space 
representing the cursor’s column position. Column addresses start with 
zero. 


System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


Session Information Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the session management portion of the workstation program. The 
function ID is in byte 1, and the error number is in byte 0. Session 
information services return codes use a function ID of X‘6B’. The error 
codes that can be received for this service are: 


Code Meaning 


X‘00’ Successful completion. 

X‘02’ Specified session ID is invalid. 

X‘06’ Specified session ID not in use. 

X‘0C’ Byte 0 of the parameter list is not zero on request. 


See Appendix H, “Return Codes,” for more information. 


Coding Example 


. 
, 


; PARAMETER LIST FOR QUERY SESSION 


CRRETNCD 
CRFXNID 

CRSESSID 
CRCURSOR 
CRROWADD 
CRCOLADD 


DB 
DB 
DB 
DB 
DB 
DB 


OOO000 


me Me Ne Ne Ne Ne 


Query Session Cursor 


CURSOR 


RETURN CODE 
FUNCTION ID 
SESSION ID 
CURSOR TYPE 
ROW ADDRESS 
COLUMN ADDRESS 


; INITIALIZE PARAMETER LIST FOR QUERY SESSION CURSOR 


MOV 
MOV 
MOV 
MOV 


CRRETNCD , OOH 
CRFXNID,OOH 
AL,SESSID 

CRSESSID,AL 


=e Se Ne Ne 


RETURN CODE MUST 
FUNCTION ID MUST 
SESSION ID IN 
PARAMETER LIST 


QO BEFORE REQUEST 
QO BEFORE REQUEST 


; INITIALIZE REGISTERS FOR QUERY SESSION CURSOR 


. 
! 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


AH ,O9H 
AL, OBH 
BH, 80H 
BL, 20H 
CX, OF FH 
DX, SESSMGR : 
DI, SEG CRRETNCD ;: 
ES,DI ? 
DI,OFFSET CRRETNCD ; 


NAME RESOLUTION FOR SESSMGR 
SEGMENT ADDRESS OF PARAMETER LIST 
IN ES 

OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR QUERY SESSION CURSOR SERVICE 


. 
t 


INT 


7AH 
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Introduction 


Introduction 


This chapter describes how to code requests for the keyboard services 
provided by the API. 


The keyboard services allow your application program to read and write 
keystroke data from a specified session, to disable and enable operator 
input from the keyboard of a specified session, and to notify the 
workstation program of the status of your application program’s keystroke 
processing. 


A recommended way of performing keystroke processing is for an 
application program to create a separate task (using the Create Task Entry 
service) that processes keystrokes in a loop until the terminating keystroke 
is detected. The application program should use the Set Task Ready service 
to set the task to the ready state and cause it to run. 


As an example, the keystroke processing task might consist of the 
following: 


1. 


An initialization section that would perform the system functions 
needed to obtain information required by the task. Some functions that 
the initialization section may include are: 


e Creating an input queue and if necessary an event queue 
e Requesting any query services needed 
e Readying the keystroke processing task. 


A key processing section that should first connect to any sessions with 
which the task will interact; it then will loop while performing the Read 
Input and Write Keystroke functions as required as well as any other 
actions required to process keystrokes. This section could continue to 
loop until some terminating condition was detected, such as some 
predefined terminating keystroke. 


Note that while this task is in the process of doing a Read Input 
function with a WAIT option, it will be suspended until something 
appears on its input queue. This means that no other processing can be 
done by this task until either a keystroke is pressed on the keyboard, or 
a 4-byte item is enqueued to the task’s input queue by another task. 

The task may also do a Read Input function with a NOWAIT option. In 
this case, control will be returned if there is nothing on the queue and 
processing can be done without pressing another keystroke or receiving 
input from another task. In either case, the processing loop can detect 
the value returned in the parameter list as a keystroke, continue 
processing, and determine the need to terminate either by the keystroke 
value or by some other mechanism. It would then avoid doing another 
Read Input and set itself unready. | 


Introduction 


3. A cleanup section that will be be run when the task is signaled in some 
way to end its processing. This section would disconnect from all 
services that it had connected to and delete any items it had created, 
such as the input queue. When its cleanup activities are completed, 
this section could signal some controlling task that it is done, and set 
itself unready. This prevents it from being dispatched again. The 
controlling task could delete the key processing task prior to returning 
to DOS. 


Scan Code/Shift States 


The Keyboard Services utilize scan codes/shift states to identify 3270 PC 
keyboard events. Each keytop on the keyboard is represented by a unique 
scan code byte. An additional shift state byte describes the condition of 
keyboard modifying keys (that is, Upshift, Caps Lock, Alt, and Ctrl). 


The scan code values are listed in Appendix A and are shown on foldouts at 
the back of this book. These 3270 PC API values are not the same as those 
received when reading keystrokes via standard PC keyboards (for example, 
using the BIOS method). For information on the standard PC scan codes, 
refer to the IBM Personal Computer Technical Reference manual. 


Regardless of what keyboard you have attached, the scan codes/shift states 
you either receive or send are the values for the 3270 PC keyboard. These 
3270 PC API scan codes/shift states must be used in all cases involving the 
use of the keyboard service API. See Appendix A of this manual for a list 

of these scan code/shift state values. 


Note that, internal to the workstation program, keystrokes are represented 
by four bytes as indicated by bytes 8 through 11 of the Read Input 
parameter list. 


The 3270 PC keyboard has many more keytops than a standard PC 
keyboard. However, only those 3270 PC keytops that are found on the 
standard PC are available to an application using the standard PC methods 
of reading keystrokes. Alternatively, all 3270 PC keytops (except the work 
station control keytops) can be made available to the connecting 
application via the Read Input service; the Connect to Keyboard service 
with the intercept option of “All Keystrokes” is used to enable this 
alternative. 


The API scan codes/shift states sent by an application are processed using 
the Write Keystroke service; as a result, a receiving application using 
standard PC methods can expect the same results as if running on a 
standard PC. 


The keyboard shift state is indicated by a 1-byte value that indicates which 
of the functions or characters printed on the keytop of a given position is 
being sent. The shift state byte is described in Appendix A. Note that PC 
sessions require the use of bits 2 and 3 of that byte to determine which of 
the two shift keys was depressed, while bit 7 alone is sufficient for all other 
sessions to recognize the upshifted condition. 
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Keytop Characteristics 
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Four types of keytop characteristics are used on the 3270 PC keyboard: 


1. “Make Only,” where one scan code is sent for each depression of the 
key, no matter how long it is held down. 


2. “Make/Break,” where a scan code is sent when the key is pressed 
(make) and then a pair of scan codes is sent when the key is released 
(break). The first of the two break scan codes is X‘F0’, which indicates 
that a key is released. The second scan code is that of the key that was 
released. (This second scan code is the same as that sent when the key 
is pressed.) 


3. “Typematic,” where a single scan code is sent when the key is pressed 
and, if after a short time the key is not released, that same scan code is 
sent every 100 milliseconds until the key is released. 


4, “Typematic Make/Break,” which is the same as that described for 
“Typematic,” except that upon release the breaking pair of scan codes is 
sent just as described for the “Make/Break” type of keys. 


With the workstation program loaded, the characteristics of the keyboard 
are altered to match those expected by the session that is currently active. 
From a keystroking perspective, there are only two types of sessions: PC 
sessions (those that appear on a standard PC) and non-PC sessions (host, 
notepad, and WS Ctrl). The non-PC sessions are all coded to use the host 
style of keyboard characteristics, while the PC sessions expect to receive 
the standard PC style. 


The keytop characteristics (with API scan codes in hex) are as follows: 


e PC and non-PC sessions; for all cases, the following keytops are “Make 
Only.” (Regardless of the active session, these keytop scan codes are 
always sent to the WS Ctrl session.) 


= ws Ctrl (scan code 04) 
— ChgSc/Jump (scan code 03) 
~— Enlarge ( a+{] ) (scan code 01) 


e PC sessions; all keytops (except those in item 1) are “Typematic 
Make/Break” to match the characteristics of the PC’s keyboard. 


e Non-PC sessions; 

~ The following keys are “Make/Break”: 
Upshift, left and right (scan codes 12 and 29) 
Alt, left and right (scan codes 19 and 39) 


Caps Lock (scan code 14) 
Ctrl (scan code 09) 


Introduction 


— The following keys are “Make Only”: 


Key(s) Scan Code(s) 
PF1 through PF24 See page FO-1 
PAI through PA3 67, 6E and 6F 
Help 05 

Clear 06 

WS Ctrl 04 

Finish 0c 
ChgSc/Jump 03 

Erase EOF OB 

Print 83 

Copy/Auto 0A 

Enlarge ( o+-(] ) 01 

Reset ia 

Enter 58 

Insert ( & ) 65 

Delete ( @ ) 6D 

Home (“\, ) 62 

On the Numeric Keypad 

Esc 76 

NumLk 77 

,/SerLk ; 7E 

Space 84 

./Del 71 

Enter/+ 79 


— All other keytops are “Typematic.” 


Care should be taken when sending keystrokes between differing session 
types (that is, reading a PC keyboard and sending the results to a non-PC 
session, or vice versa), to filter the keystroke characteristics in such a way 
as to match what the destination session expects. The same care should be 
taken for the scan codes. For example, a host session does not expect the 
Enter key to be “Make/Break” and may treat the breaking scan code as a 
second Enter key. Similarly, a scan code for the Esc key has no meaning to 
a host session and, if sent, will terminate a Write Keystroke request with 
an X‘10’ error condition. 


Attention Identifier (AID) Keys 


Attention Identifier (AID) keys are those keys that, when pressed in a host 
session, cause immediate host interaction. The term AJD applied to these 
keys is meaningful only during a host session. In a host session, AID keys 
are “Make Only” and references to AID keys do not take into account 
typematic or make/break characteristics. 
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The Connect to Keyboard service with the intercept option of “AID 
keystrokes only” allows the API program to control host mainframe 
interactions without interfering with normal data entry keystrokes. 


The keytops treated as AID keys during a host session are: 


PF1 through PF24 
Enter ( — ) 
Clear 

SysRq 

CrSel 

Test 

Attn 

PAI through PA3 


Work Station Control Keys 


Special Keys 
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Work station control keys are those keyboard keys that, when pressed, have 
their scan codes routed to the WS Ctrl session or the interceptor of the WS 
Ctrl session’s keystrokes. This routing occurs without regard for what 
session is active at the time. These keys have no meaning to any other 
session and will be rejected if their scan codes are sent to those sessions 
through the Write Keystroke service. 


The keytops treated as work station control keys are: 


WS Ctrl (in the upper and lower shift states, but not in the control shift 
or alternate shift states). 

ChgSc 

Jump 

Enlarge ( a+] ) 


There are some additional API scan codes used by the workstation program 
that do not appear in the scan code table, but do appear in the Read Input 
and Write Keystroke service requests: 


e ‘FQ’ is used to indicate that a make/break type key is being released and 
that the next scan code to follow represents the key being released. 


e ‘7F’ is sent by the workstation program to notify sessions of the current 
shift state of the keyboard. The workstation program sends this scan 
code whenever the real keyboard is reattached to a session; this ensures 
that the session interprets the current shift state as that perceived by 
the keyboard operator. This scan code occurs whenever a session is 
jumped into or whenever keystrokes have been sent to a session other 
than directly from the keyboard. To the session receiving it, this scan 
code means “align the session shift state to match the shift state sent 
with this scan code.” 


Introduction 


ASCII/ASCII Mnemonics 


Keyboard Services 


The Keyboard Services API supports an ASCII option on the Read Input 
and Write Keystroke API services to allow applications to send and 
receives keys in ASCII or ASCII mnemonics. The ASCII values that can be 
sent or received include: 


All standard ASCII characters representing keys that can be received 
from the keyboard 


ASCII mnemonics that represent HOST and PC keystrokes that do not 
have ASCII codes. All mnemonics are two bytes, three bytes, four bytes, 
or six bytes long. All mnemonics start with @. 


Note: When intercepting keystrokes with ASCII, only the Make key is 
returned. Shift, break, and shift alignment keys are not returned 
using this option. 


Appendix A contains a complete list of all ASCII values and their 
corresponding characters. 


The keyboard services provided by the API are: 


Connect to Keyboard Service: Use this service to connect to a 
session for keyboard services. 


Disconnect from Keyboard Service: Use this service to disconnect 
from a session for keyboard services. 


Read Input Service: Use this service to read keystroke data from a 
session. 


Write Keystroke Service: Use this service to write keystroke data 
to a session. 


Disable Input Service: Use this service to disable operator input to 
the session. 


Enable Input Service: Use this service to reenable operator input to 
the session. 


Post Status Code Service: Use this service to notify the workstation 


program of the status of your application program’s keystroke 
processing. 
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Requesting the Keyboard Services 


To request any of the keyboard services, load the registers and the 
parameter list with the proper values, and use the INT 7AH instruction to 
signal the workstation program that it has a request to process. 


Note: Before your application can request the keyboard services, it must 
request the Name Resolution service, using KEYBOARD as the gate 
name in the parameter list. 


Return Codes for the Keyboard Services 


Each keyboard service has two return codes associated with it: a system 
return code and a keyboard management return code. Both types of return 
codes are 2-byte values made up of a function ID and an error number. The 
function ID indicates the portion of the workstation program in which the 
error occurred. The error number indicates the specific type of error that 
has occurred. An error number of X‘00’ always indicates a successful 
acceptance or completion of the request. 


e System Return Codes: 


After your application has requested a keyboard service, the CH and CL 
registers contain a return code generated by the request processing 
portion of the workstation program. The function ID is in the CH 
register, and the error number is in the CL register. System return 
codes use a function ID of X‘12’. The error codes that can appear are: 


Code Meaning 


X‘00’ Request accepted. 

X‘05’ Invalid index specified. 
X‘07’ Invalid reply specified. 
X‘08’ Invalid wait type specified. 
X‘0B’ RQE pool depleted. 

X‘0F’ Invalid environment access. 
X‘34’ Invalid gate entry. 


These system return codes apply to all keyboard services. 
e Keyboard Services Return Codes: 


After a requested keyboard service is completed, bytes 0 and 1 of the 
parameter list contain a return code generated by the keyboard 
management portion of the workstation program. The function ID is in 
byte 1, and the error number is in byte 0. Keyboard services return 
codes use a function ID of X‘62’. The error numbers that can appear are 
specific to the service that was requested and are included in the 
descriptions of each service. 


See Appendix H, “Return Codes,” for more information. 


Connect to Keyboard 


Keyboard Service X‘01’: Connect to Keyboard 


Register Values 


Use this service to connect to a session for keyboard services. 


On Request On Completion 

AH = X‘09’ CH = X‘12’ 

AL = X‘0l’ CL = Return code 

BH = X‘80’ 

BL = X‘20’ The contents of registers 
CX = X‘0000’ AX, BX, DX, ES, and DI 
DX = Resolved value for KEYBOARD are unpredictable. 

ES = Segment address of the parameter list 

DI = Offset address of the parameter list 


Parameter List Format 


Offset | Length on Request on Completion 
Return code 
Function ID (X'62’) 
Unchanged 
Reserved 


1 word Input queue ID or | Unchanged 
Zero 


1 byte Intercept options Unchanged 
1 byte First connection indicator 


hc 

or zero 
ee 
aa 


Parameter Definitions 


Request Parameters: 
e The session ID is the ID of the session you want to connect to. 


e The event queue ID is the ID of a fixed-length queue that the 
workstation program uses to notify you when the program running in 
another session has been stopped. If you intend to interact with 
programs in other personal computer sessions, using this event queue is 
a way of finding out when any of those programs is stopped. Use the 
Create Queue service to create this fixed-length queue, and use the 
Dequeue Element service to obtain the event information. This 
parameter is optional and should be set to zero if not used. 
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The event that can be reported is as follows:. 


ee ee ol 
X02" (code) 
X‘62’ (function ID) 


This event indicates that the specified session has been 
disconnected. 


The input queue ID is the ID of a fixed-length queue used to receive 
intercepted keystrokes typed at a session. Use the Create Queue 
service to create this fixed-length queue. This parameter is optional 
and should be set to zero if not used. If this parameter is set to a 
nonzero value, then a valid intercept option must also be set. 
Keystrokes can be intercepted from the specified session by requesting 
the Read Input service. 


The intercept options specify which types of keystrokes are to be 
intercepted from the specified session. If this byte is nonzero, you must 
also supply an input queue ID. The bits in the intercept options byte 
are as follows: 


ee ES 
AID keystrokes only All keystrokes 


— Bit 0 set to 1 indicates that only keystrokes that would normally 
generate an AID in a host session are to be sent to your application 
program. 


— Bit 1 set to 1 indicates that all keystrokes in the session are to be 
sent to your application program, including AID keys. 


— Bits 2 through 7 are reserved and should be set to all zeros. 


Completion Parameters: 


The first connection indicator is set to X‘FF’ if this is the first time a 
Connect to Keyboard request has been made to this session. 


~ If connecting to a session defined at configuration time or by an 
INDSPLIT or INDMERGE command, the workstation program has 
already issued a Connect to Keyboard request for the session. 
Therefore, a value of X‘FF’ indicates an error condition. 


— If connecting to a session defined by your application program by a 
Define Presentation Space service request, the workstation program 
will not have issued a prior Connect to Keyboard request for that 
session. Therefore, a value of X‘FF’ is normal. 


Connect to Keyboard 


Return Codes 
e System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


e Keyboard Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the keyboard management portion of the workstation program. The 
function ID is in byte 1, and the error number is in byte 0. Keyboard 
services return codes use a function ID of X‘62’. The error codes that 
can be received for this service are: 


Code Meaning 
X‘00’ Successful completion. 


X‘01’ Invalid intercept option. 
X‘02’ Invalid session ID. 


X‘04’ Session busy; cannot connect at this time. 

X‘0C’ Byte 0 of the parameter list is not zero on request. 

X‘12’ Request failed; an autokey record operation is in progress. 
X‘14’ Request failed; an autokey playback operation is in progress. 


See Appendix H, “Return Codes,” for more information. 


Usage Notes 


e Your application program can be connected simultaneously for 
keystroke data to each of the host, notepad, work station control, and 
personal computer sessions that your 3270 Personal Computer is 
customized to support. 


e The recommended size for input queues is 50 bytes. 


e A maximum of two connections for keyboard services can be made to a 
session at any one time. If your session was defined at configuration 
time or by issuing an INDSPLIT or INDMERGE command, one 
connection has already been made to the session by the workstation 
program. 


e The workstation program issues Connect to Keyboard service requests 
for each configured session to provide the capability for the session to 
receive and process keystrokes. 


A session defined by your application program (by a Define 
Presentation service request) requires that a Connect to Keyboard with 
an All Keys Intercept option be issued in order to receive and process 
keystrokes. Note that this implies that the application must also 
provide the keystroking task for such sessions. A second Connect to 
Keyboard request can be issued relative to a Define Presentation Space 
session. 
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eo "=e “6 


.CKRETNCD 


CKFXNID 

CKSESSID 
CKRESRV1 
CKEVENTQ 
CKKEYSTQ 
CKOPTION 
CK1STCON 


° 
‘ 


9aoO0O000000 


a i il i i al Sl) 


PARAMETER LIST FOR CONNECT TO KEYBOARD 


RETURN CODE 

FUNCTION NUMBER 

SESSION ID 

RESERVED 

EVENT QUEUE ID 

INPUT QUEUE ID 

OPTION BYTE 

FIRST CONNECTION INDICATOR 


; INITIALIZE PARAMETER LIST FOR CONNECT TO KEYBOARD 


° 
’ 


~e 8 Ne 


=e ™e Se 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


INT 


CKRETNCD , 00H 
CKFXNID, 00H 
AL,SESSID 
CKSESSID,AL 
CKOPTION ,01000000B 
AX, KEYSTOQ 
CKKEYSTQ , AX 

AX , EVENTOQ 
CKEVENTQ , AX 


INITIALIZE REGISTERS FOR CONNECT 


AH,09H 

AL,01H 

BH, 80H 

BL, 20H 

CX, 00H 

DX , KEYBOARD 

DI, SEG CKRETNCD 
ES,DI 

DI,OFFSET CKRETNCD 


7AH 


=e ™e Ne Ne Ne Oe Ne Ne NO 


RETURN CODE MUST QO BEFORE REQUEST 
FUNCTION ID MUST O BEFORE REQUEST 
SESSION ID INTO THE LIST 


OPTION = INTERCEPT ALL 
KEYSTROKE QUEUE ID INTO THE LIST 


EVENT QUEUE ID INTO THE LIST 


TO KEYBOARD ( 


° 
a 
. 
f 
‘ 
° 
‘ 


RESOLVED VALUE FOR 'KEYBOARD' 
SEGMENT ADDRESS OF PARAMETER LIST 
IN ES 

OFFSET OF PARAMETER LIST IN DI 


SIGNAL WORKSTATION PROGRAM FOR CONNECT TO KEYBOARD SERVICE 


Disconnect from Keyboard 


Keyboard Service X‘02’: Disconnect from Keyboard 


Use this service to disconnect from the session when you are finished using 
the keyboard services. 


Register Values 


On Request On Completion 

AH = X‘09’ CH = X‘12’ 

AL = X‘02’ CL = Return code 

BH = X‘80’ 

BL = X‘20’ The contents of registers 
CX = X‘0000’ AX, BX, DX, ES, and DI 
DX = Resolved value for KEYBOARD are unpredictable. 

ES = Segment address of the parameter list 

DI = Offset address of the parameter list 


se a 
Offset | Length on Request on Completion 
fo [ityte [Must be zero [Return code —_— 


Connector’s task ID Unchanged 


Parameter Definitions 
Request Parameters: 


e The session ID is the ID of the session you want to disconnect from. 
The session must have been previously connected to the keyboard 
through a Connect to Keyboard service request. 


e The connector’s task ID is needed only if the task that requested the 
Connect to Keyboard service for this session is different from the task 
requesting the Disconnect from Keyboard service. This parameter is 
optional and should be set to zero if not used. 
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Return Codes 


Usage Notes 
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System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


Keyboard Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the keyboard management portion of the workstation program. The 
function ID is in byte 1, and the error number is in byte 0. Keyboard 
services return codes use a function ID of X‘62’. The error codes that 
can be received for this service are: 


Code Meaning 


X‘00’ Successful completion. 

X‘02’ Invalid session ID. 

X‘04’ The session is not connected for keyboard services. 
X‘0C’ Byte 0 of the parameter list is not zero on request. 


See Appendix H, “Return Codes,” for more information. 


This service also enables operator input to the session if it was 
previously disabled through a Disable Input service request. 


Before exiting, your application program must use the Disconnect from 
Keyboard service for each session that was connected for keystroking 
data. This service should be requested at all error exit points as well as 
during normal processing. 


Disconnect from Keyboard 


Coding Example 


° 
’ 


; PARAMETER LIST FOR DISCONNECT FROM KEYBOARD 


DKRETNCD DB 


fe) ; RETURN CODE 
DKFXNID DB O ; FUNCTION NUMBER 
DKSESSID DB 0 7 SESSION ID 
DKRESRV1 DB 0 ; RESERVED 

0 ; 


DKTASKID DW CONNECTOR'S TASK ID 


; INITIALIZE PARAMETER LIST FOR DISCONNECT FROM KEYBOARD 


MOV DKRETNCD,OOH 
MOV DKFXNID,OOH 
MOV AL,SESSID 
MOV DKSESSID,AL 
MOV AX,TASKID 
MOV DKTASKID,AX 


RETURN CODE MUST = O BEFORE REQUEST 
FUNCTION ID MUST = O BEFORE REQUEST 
SESSION ID INTO THE LIST 


CONNECTOR'S TASK ID INTO THE LIST 


a i eT a eT | 


; INITIALIZE REGISTERS FOR DISCONNECT FROM KEYBOARD 


MOV AH,09H 
MOV AL,02H 
MOV _—-BH, 80H 
MOV BL,20H 
MOV CX,O00H 
MOV DX,KEYBOARD ; RESOLVED VALUE FOR 'KEYBOARD' 
MOV DI, SEG DKRETNCD  ; SEGMENT ADDRESS OF PARAMETER LIST 
MOV ES,DI ; IN ES 
MOV DI,OFFSET DKRETNCD ; OFFSET OF PARAMETER LIST IN DI 
; SIGNAL WORKSTATION PROGRAM FOR DISCONNECT FROM KEYBOARD SERVICE 
v 


INT 7AH 
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Read Input 


Keyboard Service X‘03’: Read Input 


Register Values 


Use this service to read intercepted keystroke data destined for the session. 
An options byte is set to indicate whether the Read is done with scan 
code/shift states or with ASCII mnemonics. This service returns the scan 
code/shift state and/or the ASCII mnemonic for one keystroke with each 
request made. 


On Request On Completion 

AH = X‘09’ CH = X‘12’ 

AL = X‘03’ CL = Return code 

BH = X‘80’ 

BL = X‘20’ The contents of registers 
CX = X‘0000’ AX, BX, DX, ES, and DI 
DX = Resolved value for KEYBOARD are unpredictable. 

ES = Segment address of the parameter list 

DI = Offset address of the parameter list 


Parameter List Format 
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ome [vgs [oe [SE 
Offset | Length on Request on Completion 

}0[ibyte | Mustbezero | Returncode 
2 | ibyte [Session ID | Unchanged 
ae 


Connector’s task ID Unchanged 


The bits in the options byte are as follows: 
ae Cee 
aso fo 


e Bit 0 set to 1 means to read the keystroke in ASCII format. 


Ti bo 
?) 
— 
TM 
TM 
Zz 
io) 
= 
iY) 
fete 
ot 


Bit 2 set to 1 means to read the keystroke in scan code/shift state 
format. | 


Note: Choose either ASCII or scan code/shift state format. Do not select 
both (that is, do not set bits 0 and 2 equal to 1). 


Read Input 


e Bit 4 set to 1 means to read the keystroke with the NOWAIT option. If 
a keystroke is not available on the queue when this is issued, a return 
code of X‘09’ will be placed in the parameter list and control returned to 
the caller. If the bit is not set, the calling test will be suspended until 
keystroke data appears on the task input queue. 


The remainder of the parameter list depends on whether you have specified 
the scan code/shift state format or the ASCII/ASCII mnemonic format. 


If you have selected the scan code/shift state format, the parameter list is as 
follows: 


Contents on Contents on 
Offset | Length Request (SC/SS) Completion (SC/SS) 
7__|ibyte [Reserved Sid Reserved 
}8_fibyte | Reserved = Scan code of the key 


7 
Shift state of the key 
i 


If you have selected the ASCII/ASCII mnemonic format, the parameter list 
is as follows: 


Contents on Contents on 
Offset | Length Request (ASCII) Completion (ASCID 


7 1byte Reserved Length of 
ASCII/ASCII 
mnemonic returned in 
bytes 8 — 13 


8 — 13 | 6 bytes Reserved ASCII/ASCII 
mnemonic 
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Request Parameters: 


e The session ID is the ID of the session from which keystroke data is 
intercepted. 


e The connector’s task ID is needed only if the task that requested the 
Connect to Keyboard service for this session is different from the task 
requesting the Read Input service. This parameter is optional and 
should be set to zero if not used. 


Completion Parameters for Scan Code/Shift State Option: 


Keystroke data is sent to a session in a format that uses four bytes of data 
to represent the key being sent. The first byte is called the scan code, and 
the second byte is called the shift state. The third and fourth bytes are 
particular to the device being used and, for a keyboard, should normally be 
X‘0100’. 

e The scan code represents a particular key position on the keyboard. 

e The shift state indicates which of the possible characters or functions 
located at that key position is being sent. The possible shift states are 
the lower shift, the upper shift, the alt shift, and the ctr] shift. 

Appendix A lists the scan codes for each key position and describes the 

format of the shift state byte. In addition, the foldout for the IBM 3270 PC 

keyboard (at the back of this book) shows the scan codes for each key 
position on the keyboard. 


Completion Parameters for ASCII/ASCII mnemonic option: 


e ASCII/ASCII mnemonics are from 1 to 6 bytes long. ASCII mnemonics 
start with @. 


e The length of field is the length of the ASCII code or ASCII mnemonic. 
Note: Any bytes left unused will remain unchanged. 


See Appendix A for a list of all the ASCII/ASCII mnemonics that can be 
received. 


Return Codes 


Read Input 


Note: If the shift state of the key pressed does not contain a unique 
ASCII/ASCII mnemonic or if multiple shift states are active, ASCII 
mnemonics for the shift state will be prefixed. The valid shift prefix 
mnemonics are: 


@A - Alt shift active 
@S - Upshift active 


@r - Ctrl shift active. 


An example of this would be pressing alt-a. The ASCII mnemonic 
returned would be @Aa. If the Ctrl-shift-A were pressed, the ASCII 
mnemonic returned would be @rA. 


e System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


e Keyboard Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the keyboard management portion of the workstation program. The 
function ID is in byte 1, and the error number is in byte 0. Keyboard 
services return codes use a function ID of X‘62’. The error codes that 
can be received for this service are: 


Code 


X‘00’ 
X‘01’ 
X‘02’ 
X‘04’ 
X‘09’ 
X‘0C’ 
X‘10’ 


Meaning 


Successful completion. 

Invalid intercept option (see Note). 

Invalid session ID. 

The session is not connected for keyboard services. 
Queue empty, no keystroke available. 

Byte 0 of the parameter list is not zero on request. 
Invalid keystroke. 


Note: An invalid intercept option means that the application is trying to do 
a Read Input when no Read options were specified on the connect. 


See Appendix H, “Return Codes,” for more information. 
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To be able to use the Read Input service, you must do the following 
when you request the Connect to Keyboard service: 


— Specify which types of keystrokes are to be intercepted from the 
connected session 


— Provide the ID of a fixed-length queue to be used by the workstation 
program to store the intercepted keystroke data. 


The scan code and shift state returned by this service are not the same 
as those returned by BIOS or DOS read keys. 


When using the Read Input service with the scan code option for a PC 
session, you must keep in mind that each key will generate an X‘FO’ 
scan code if the key is breaking, followed by the scan code of the key. 
See “Special Scan Codes” in Appendix A. 


It is recommended that each Read Input request be followed by a Post 
Status Code request, particularly if keystrokes are rejected for any 
reason. 


Applications running on non-3270 PC XT hardware that send keystrokes 
to or receive keystrokes from the host session will not run on Uni-DOS. 


Applications using the keyboard services should be well-behaved. 
Additionally, if your application is using the API to another PC session, 
then that session must also be well-behaved. 


Coding Example 


° 
/ 


° 
c 


i 
RKRETNCD 


PARAMETER LIST FOR READ INPUT 


DB 0O : 
RKFXNID DB O ; 
RKSESSID DB 0 ; 
RKRESRV1 DB 0O : 
RKTASKID DW 0O ; 
DB 20H : 
RKRESRV2 DB O : 
RKSCANCD DB 0O ; 
RKSHIFST DB 0O H 
DB O : 
DB O : 


, 


~e me Ne 


INITIALIZE PARAMETER LIST FOR READ 


MOV RKRETNCD,OOH ; 
MOV RKFXNID,OOH ; 
MOV AL,SESSID ; 
MOV RKSESSID,AL ; 
MOV AX,TASKID ; 
MOV RKTASKID,AX : 


INITIALIZE REGISTERS FOR READ INPUT 


MOV AH,09H 
MOV AL,03H 
MOV  BH,80H 
MOV BL,20H 
MOV CX,0O0H 
MOV DX,KEYBOARD : 
MOV DI, SEG RKRETNCD ; 
MOV ES,DI ; 
MOV DI,OFFSET RKRETNCD ; 


Read Input 


RETURN CODE 

FUNCTION NUMBER 
SESSION ID 

RESERVED 

CONNECTOR'S TASK ID 
MUST BE 20H FOR SCAN CODES 
RESERVED 

SCAN CODE OF THE KEY 
SHIFT STATE OF THE KEY 
01H ON RETURN 

OOH ON RETURN 


INPUT 


RETURN CODE MUST 0 BEFORE REQUEST 
FUNCTION ID MUST O BEFORE REQUEST 
SESSION ID INTO THE LIST 


CONNECTOR'S TASK ID INTO THE LIST 


RESOLVED VALUE FOR 'KEYBOARD' 
SEGMENT ADDRESS OF PARAMETER LIST 
IN ES 

OFFSET OF PARAMETER LIST IN DI 


SIGNAL WORKSTATION PROGRAM FOR READ INPUT SERVICE 


INT 7AH 
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Write Keystroke 


Keyboard Service X‘04’: Write Keystroke 


Use this service to send keystroke data to the session. An options byte is 
set to indicate whether the write is done with scan code/shift states or with 
ASCII/ASCII mnemonics. Appendix A contains the valid scan code/shift 
states or ASCII/ASCII mnemonics that can be sent. 


Register Values 


On Request On Completion 

AH = X‘09’ AX = Request ID 

AL = X‘04’ CH = X‘12’ 

BH = X‘80’ or X‘40’ (see Note) CL = Return code 

BL = X‘20’ or X‘00’ (see Note) 

CX = X‘0000’ The contents of registers 
DX = Resolved value for KEYBOARD BH, DX, ES, and DI are 
ES Segment address of the parameter list unpredictable. 


Ml 


DI Offset address of the parameter list 


Note: The combined contents of the BH and BL registers are either X‘8020’ 
or X‘4000’. 


e Request Register Values: 


For asynchronous processing of the Write Keystroke service request, 
set the BH register to X‘40’ and the BL register to X‘00’. When 
asynchronous processing is specified, you must request the Get Request 
Completion service to obtain the results of each Write Keystroke 
service request. 


For synchronous processing of the Write Keystroke service request, set 
the BH register to X‘80’ and the BL register to X‘20’. 


e Completion Register Values: 


If you specified asynchronous processing (the BH register = X‘40’ and 
the BL register = X‘00’ on request), the AX register contains a request 
ID that the workstation program assigned to the request. You use this 
request ID to match the results of the service obtained by the Get 
Request Completion service to a previously requested service. 
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Write Keystroke 


Parameter List Format 


Fe a a 
Offset | Length on Request on Completion 

}0 | ibyte | Must bezero [| Returncode 
ae 


Connector’s task ID Unchanged 
1 byte Options byte Unchanged 


The bits in the options byte are as follows: 


Oo ff fs fe [7 | 
asc fo fo fo 


e Bit 0 set to 1 means to write the keystroke or list of keystrokes in 
ASCII format. 


Bit 2 set to 1 means to write keystroke or list of keystrokes in scan 
code/shift state format. 


Note: Choose either ASCII or scan code/shift state format. Do not select 
both (that is, do not set bits 0 and 2 equal to 1). 


Bit 3 is set as follows: 


1 — Write a list of keystrokes. 
2 — Write a single keystroke. 


The remainder of the parameter list depends on which option you have 
specified and on whether you are writing a single keystroke or a list of 
keystrokes. 


If you are sending a single keystroke with the scan code/shift state option, 
the parameter list must be formatted as follows: 


Contents on Request Contents on Completio 
Offset | Length | (SC/SS Single) (SC/SS Single) 


18 = | A byte Scan code of the key Unchanged 
19 =| byte | Shift state of the key Unchanged 
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1 byte Number of bytes of Number of bytes of 
ASCTI/ASCII | ASCII/ASCII 
mnemonics to send (in mnemonics sent 

. bytes 8— 18) 


If you are sending a single keystroke with the ASCII option, the parameter 
list must be formatted as follows: 


Contents on Request Contents on Completio 
Offset | Length | (ASCID Single (ASCII) Single 


18-13 |6 bytes | ASCII mnemonic Unchanged 


If you are sending a list of keystrokes with the scan code/shift state option, 
the parameter list must be formatted as follows: 


Contents on Request Contents on Completio 
Offset | Length | (SC/SS List) (SC/SS List) 
1 byte Number of keys sent 


1 word Offset address of list of Unchanged 
keys 
10 1 word Segment address of list Unchanged 
of keys 


If you are sending a list of keystrokes with the ASCII option, the parameter 
list must be formatted as follows: 


Contents on Request Contents on Completio 
Offset | Length | (ASCII) (ASCII) 


i 1 byte Reserved Number of bytes of 
ASCII/ASCII 
mnemonics in the list 
that were sent 

1 word Offset address of list of Unchanged 
keys 

10 1 word | Segment address of list Unchanged 

of keys 


Write Keystroke 


Parameter Definitions 


Request Parameters: 


The session ID is the ID of the session to write the keystrokes to. 


The connector’s task ID is needed only if the task that requested the 
Connect to Keyboard service for this session is different from the task 
requesting the Write Keystroke service. This parameter is optional and 
should be set to zero if not used. 


The format of a list of scan code/shift state keystrokes is as follows: 


ee ae 2 x n (where n is the number of keys being 
sent to the session) 

[2s ibyte | Scan code of the first key being sent 

j2n 


1 byte Scan code of the second key being sent 


Shift state of the second key being sent 


Scan code of the nth key being sent 
Shift state of the nth key being sent 


Note: n=255 keys, which is the maximum value allowed. 


The format of a list of ASCII keystrokes is as follows: 


Offset 


1 word |N (where N is the number of bytes of 
ASCTII/ASCII mnemonics being sent to the 
- | session) 
2-(N+2)|N ASCII/ASCIT mnemonic of the keys being 
bytes sent 


Note: N= 255 bytes, which is the maximum value allowed. 
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e System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


e Keyboard Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the keyboard management portion of the workstation program. The 
function ID is in byte 1, and the error number is in byte 0. Keyboard 
services return codes use a function ID of X‘62’. The error codes that 
can be received for this service are: 


Code 


X*‘00’ 
X‘01’ 
X ‘02’ 


X‘04’ 
X‘0C’ 
X‘10 


X‘12’ 


Meaning 


Successful completion. 

Invalid option byte value. 

Invalid session ID, or the list of scan code/shift state 
keystrokes is longer than 255 bytes, or the list of 
ASCII/ASCITI mnemonics is longer than 255 bytes. 

The session is not connected for keyboard services. 

Byte 0 of the parameter list is not zero on request. 
Processing stopped because of invalid scan code or input 
inhibited, or invalid ASCII mnemonic. 

Processing stopped because AID key was detected; successful 
completion. 


See Appendix H, “Return Codes,” for more information. 


Usage Notes 


Write Keystroke 


The maximum number of keystrokes that can be sent is 255. 


The maximum number of ASCII/ASCII mnemonic bytes in the list that 
can be sent is 255. 


AID keys must not be embedded within a list, although one may be the 
last key in a list. The processing of a keystroke list ends when an AID 
key is processed or when a keystroke is rejected for any reason. Ifa 
return code of X‘10’ or X‘12’ is received, it is good practice to check byte 
7 of the parameter list on completion to determine how many of the 
keystrokes or how many bytes of ASCIT/ASCI mnemonics were actually 
sent before processing was ended. 


If you specified asynchronous processing (BH = X‘40’ and BL = X‘00’ 
on request), you must use the Get Request Completion service to obtain 
the results in the parameter list when the Write Keystroke service is 
completed. 


Host sessions must be functional in order for keystroke data to be 
processed. That is, if your 3270 Personal Computer is customized to 
support a host session, but no port is available for that session on the 
control unit, any keystroke data sent to that host session will not be 
processed. 


If your 3270 Personal Computer is connected to more than one control 
unit through a coaxial switch, you can switch to an alternate control 
unit by toggling the coaxial switch and pressing the Ctrl key and the 
Clear key at the same time. This sequence of keystrokes enables you to 
log on to an alternate host system without having to re-IPL the 
workstation program. 


A successful completion return code from a Write Keystroke request to 
a host session does not mean that the host has processed the keystroke. 
It indicates only that the keystroke has been successfully sent to the 
host session. 


Applications running on non-3270 PC XT hardware that send keystrokes 
to or receive keystrokes from the host session will not run on Uni-DOS. 


Applications using the keyboard services should be well-behaved. 


Additionally, if your application is using the API to another PC session, 
then that session must also be well-behaved. 
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. 
f 


; PARAMETER LIST STRUCTURE FOR WRITE KEYSTROKE 


WRKYPAR1 
WKRETNCD 
WKFXNID 

WKSESSID 
WKRESRV1 
WKTASKID 
WKOPTION 
WKNUMKEY 
WKSCNCOD 
WKSHFST 

WRKYPAR1 


WRKYPARM 


WKLSTOFF 
WKLSTSEG 
WRKYPARM 


. 
c 


9) 
iz 
wW 
G 
Q 


DB 


OoO0000000 


STRUC 


DB 
DW 
DW 


ENDS 


8 DUP (00) 
0 
0 


se Me Ne Ne Ne Ne Se Ne Ne 


~e Ne 


RETURN CODE 

FUNCTION NUMBER 
SESSION ID 

RESERVED 

CONNECTOR'S TASK ID 
OPTIONS BYTE 

KEYS SENT SUCCESSFULLY 
SCAN CODE OF THE KEY 
SHIFT STATE OF THE KEY 


t 


OFFSET OF LIST OF KEYSTROKES 
SEGMENT OF LIST OF KEYSTROKES 


; ALLOCATE STORAGE FOR THE PARAMETER LIST 


WKPARLST WRKYPARM <> 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


WKPARLST.WKRETNCD , OH 
WKPARLST.WKFXNID,0OH 
AL,SESSID 
WKPARLST.WKSESSID,AL 
AX, TASKID 
WKPARLST .WKTASKID , AX 


; IF SENDING ONE KEYSTROKE 


; IF SENDING A 


MOV 
MOV 
MOV 
MOV 


MOV 
MOV 


MOV 
MOV 
MOV 
MOV 


MOV 
MOV 


AL, SCANCD 
WKPARLST.WKSCNCOD , AL 
AL, SHIFST 
WKPARLST.WKSHFST,AL 


AL,20H 
WKPARLST.WKOPTION, AL 


LIST OF KEYSTROKES 


AX,OFFSET LIST 
WKPARLST .WKLSTOFF , AX 
AX,SEG LIST 
WKPARLST.WKLSTSEG , AX 


AL, 30H 
WKPARLST.WKOPTION,AL 


; SET UP THE PARAMETER LIST FOR WRITE 


=e Ne Se Me Ne ONO 


=e we Ne Ne Ne MO NO 


“eo Ne Ne Ne 


=e ome 


KEYSTROKE 


RETURN CODE MUST BE O FOR THE CALL 
FUNCTION ID MUST BE O FOR THE CALL 
SESSION ID INTO THE LIST 


CONNECTOR'S TASK ID INTO THE LIST 


PUT THE SCAN CODE INTO THE 
PARAMETER LIST 

PUT SHIFT STATE INTO THE 
PARAMETER LIST 


PUT THE OPTION BYTE FOR SENDING SCAN 
CODES ONE CHARACTER IN THE PARM LIST 


PUT THE OFFSET ADDRESS OF THE LIST 
INTO THE PARAMETER LIST 

PUT THE SEGMENT ADDRESS OF THE LIST 
INTO THE PARAMETER LIST 


PUT THE OPTION BYTE FOR SENDING A 
LIST OF CHARS. IN THE PARM LIST 


‘ 


, 


Write Keystroke 


SET UP THE REGISTERS FOR WRITE KEYSTROKE 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


AH,O9H 

AL ,O4H 

BH, 40H 

BL, 40H 

CX, 00H 

DX , KEYBOARD 

DI, SEG WKPARLST 
ES,DI 

DI, OFFSET WKPARLST 


; RESOLVED VALUE FOR 'KEYBOARD' 

; GET SEGMENT ADDRESS OF PARM LIST 
; AND PUT IT IN ES 

; SET DI TO OFFSET OF PARM LIST 


SIGNAL WORKSTATION PROGRAM FOR WRITE KEYSTROKE SERVICE 


INT 


7AH 
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Keyboard Service X‘05’: Disable Input 


Use this service to disable operator input to the session. 


Register Values 


On Request On Completion 

AH = X‘09’ CH = X‘12’ 

AL = X‘05’ CL = Return code 

BH = X‘80’ 

BL = X‘20’ The contents of registers 
CX = X‘0000’ AX, BX, DX, ES, and DI 
DX = Resolved value for KEYBOARD are unpredictable. 

ES = Segment address of the parameter list 


Offset address of the parameter list 


Contents Contents 
Offset | Length on Request on Completion 
T byte 


eee 


Connector’s task ID Unchanged 


Parameter Definitions 
Request Parameters: 


e The session ID is the ID of the session whose keyboard you want to 
disable. 


e The connector’s task ID is needed only if the task that requested the 
Connect to Keyboard service for this session is different from the task 
requesting the Disable Input service. This parameter is optional and 
should be set to zero if not used. 
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Return Codes 


Usage Notes 


Disable Input 


System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


Keyboard Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the keyboard management portion of the workstation program. The 
function ID is in byte 1, and the error number is in byte 0. Keyboard 
services return codes use a function ID of X‘62’. The error codes that 
can be received for this service are: . 


Code Meaning 


X‘00’ Successful completion. 

X ‘02’ Invalid session ID. 

X‘04’ The session is not connected for keyboard services. 
X‘0C’ Byte 0 of the parameter list is not zero on request. 


See Appendix H, “Return Codes,” for more information. 


Keystrokes typed on the keyboard of a session can become intermixed 
with the keystroke data that your application program is sending to 
that session. To prevent this, you can disable the processing of 
keystrokes typed on the keyboard of the session by using this service. 


Using the Disable Input service on the work station control session 


causes the work station control session to become active with operator 
inputs disabled. 
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. 
, 


e 
V 


DEFINE PARAMETER LIST FOR DISABLE INPUT 


DIRCODE DB 
DIFXNID DB 
DISESID DB 
DIRESRVD DB 
DICONNID DW 


, 


f 


e 
f 
° 
f 


. 
Ld 


oOO000 


se se Ne Ne Ne 


RETURN CODE 
FUNCTION CODE 
SESSION ID 
RESERVED 
CONNECTORS TASK ID 


INITIALIZE PARAMETER LIST FOR DISABLE INPUT 


MOV 
MOV 
MOV 
MOV 


MOV 
MOV 


INITIALIZE REGISTERS FOR DISABLE 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


AL, SESSID 

DISESID,AL 
DIRCODE , 00H 
DIFXNID,0O0H 


AX, CONNID 
DICONNID , AX 


AH ,09H 

AL,O5H 

BH, 80H 

BL, 20H 

CX, OOH 

DX , KEYBOARD 
DI,SEG DIRCODE 
ES,DI 

DI,OFFSET DIRCODE 


Sl i et el et TY 


KEYBOARD INPUT DISABLED FOR 
THIS SESSION 

RETURN CODE MUST=0 ON REQUEST 
FUNCTION ID MUST=0 ON REQUEST 
IF THERE IS A CONNECTORS ID 
THEN PUT IT IN THE 

PARAMETER LIST 


INPUT 


. 
td 
. 
a 
° 
f 
. 
f 


RESOLVED VALUE FOR 'KEYBOARD' 
ADDRESSABILITY OF 

PARAMETER LIST 

USING ES:DI 


SIGNAL WORKSTATION PROGRAM FOR DISABLE INPUT SERVICE 


INT 


7AH 


Enable Input 


Keyboard Service X‘06’: Enable Input 


Register Values 


Use this service to reenable operator input to the session. 


On Request On Completion 

AH = X‘09’ CH = X‘12’ 

AL = X‘06’ | CL = Return code 

BH = X‘80’ 

BL = X‘20’ The contents of registers 
CX = X‘0000’ AX, BX, DX, ES, and DI 
DX = Resolved value for KEYBOARD are unpredictable. 

ES = Segment address of the parameter list 

DI = Offset address of the parameter list 


Contents Contents 
Offset | Length on Request on Completion 
1 byte 


Oe 
1 byte 


Connector’s task ID Unchanged 


Parameter Definitions 


Request Parameters: 


e The session ID is the ID of the session whose keyboard you want to 
enable. 


e The connector’s task ID is needed only if the task that requested the 
Connect to Keyboard service for this session is different from.the task 
requesting the Enable Input service. This parameter is optional and 
should be set to zero if not used. 
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Return Codes 
e System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


e Keyboard Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the keyboard management portion of the workstation program. The 
function ID is in byte 1, and the error number is in byte 0. Keyboard 
services return codes use a function ID of X‘62’. The error codes that 
can be received for this service are: 


Code Meaning 


X‘00’ Successful completion. 

X‘02’ Invalid session ID. 

X‘04’ The session is not connected for keyboard requests. 
X‘0C’ Byte 0 of the parameter list is not zero on request. 


See Appendix H, “Return Codes,” for more information. 


Usage Notes 


e The Disconnect from Keyboard service also enables operator input to a 
session if it was previously disabled. 


e Using the Enable Input service on the work station control session 
causes the work station control session to become inactive. 
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Coding Example 


. 
f 


. 
f 


DEFINE PARAMETER LIST FOR ENABLE 


EIRCODE DB 
EIFXNID DB 
EISESID DB 
EIRESRVD DB 
EICONNID DW 


° 
f 


e 
, 


. 
, 


° 
, 


° 
' 
° 
I 


° 
’ 


OoO00 


Enable Input 


INPUT 


RETURN CODE 
FUNCTION ID 

SESSID 

RESERVED 
CONNECTOR'S TASK ID 


se “es Se Ne ONO 


INITIALIZE PARAMETER LIST FOR ENABLE INPUT 


MOV 
MOV 
MOV 
MOV 


MOV 
MOV 


AL,SESSID 
EISESID,AL 
EIRCODE , 00H 
EIFXNID,OOH 


AX , CONNID 
EICONNID, AX 


KEYBOARD INPUT ENABLED FOR 
THIS SESSION 

RETURN CODE MUST=0 ON REQUEST 
FUNCTION ID MUST=0 ON REQUEST 
IF THERE IS A CONNECTOR'S ID 
THEN STORE THE ID 

IN THE PARAMETER LIST 


bt a BT el St ee eT 


INITIALIZE REGISTERS FOR ENABLE INPUT 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


AH, 09H 
AL, 06H 

BX, 80H 

BL, 20H 

Cx, 00H 

DX , KEYBOARD 
DI,SEG EIRCODE 
ES,DI 

DI,OFFSET EIRCODE 


; RESOLVED VALUE FOR 'KEYBOARD' 
; ADDRESSABILITY OF 

; PARAMETER LIST 
; USING ES:DI 


SIGNAL WORKSTATION PROGRAM FOR ENABLE INPUT SERVICE 


INT 


7AH 
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Keyboard Service X‘07’: Post Status Code 


Use this service to notify the workstation program of the status of your 
application program’s keystroke processing. 


Register Values 


On Request On Completion 

AH = X‘09’ CH = X‘12’ 

AL = X‘07’ CL = Return code 

BH = X‘80’ 

BL = X‘20’ The contents of registers 
CX = X‘O0OFF’ AX, BX, DX, ES, and DI 
DX = Resolved value for KEYBOARD are unpredictable. 

ES = Segment address of the parameter list 

DI = Offset address of the parameter list 


CS is ae EO a 
Connector’s task ID 


Contents Contents 
Offset | Length on Request on Completion 


Parameter Definitions 
Request Parameters: 


e The session ID is the ID of the session from which keystroke data was 
intercepted. 


e The connector’s task ID is needed only if the task that requested the 
Connect to Keyboard service for this session is different from the task 
requesting the Post Status Code service. This parameter is optional and 
should be set to zero if not used. 
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Return Codes 


Usage Notes 


Post Status Code 


The status codes that can be sent to the workstation program are: 


Code Meaning 
X‘00’ The keystroke was accepted. 
X‘Ol’ The last keystroke sent was detected to be from an AID key. 


X‘02’ The keystroke was rejected or could not be processed. When 
the workstation program receives this status code, it signals 
the operator with a beep to indicate invalid input. 


System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


Keyboard Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the keyboard management portion of the workstation program. The 
function ID is in byte 1, and the error number is in byte 0. Keyboard 
services return codes use a function ID of X‘62’. The error codes that 
can be received for this service are: 


Code Meaning 


X‘00’ Successful completion. 

X‘02’ Invalid session ID. 

X‘04’ The session is not connected for keyboard services. 
X‘0C’ Byte 0 of the parameter list is not zero on request. 


See Appendix H, “Return Codes,” for more information. 


Your application program should request the Post Status Code service 
after it has processed a keystroke that was received by the Read Input 
request and was not passed on to the original session for which the 
keystroke was intended. 


The primary usage of the Post Status Code service is to provide audible 
feedback to the user in case of rejected keystrokes. 


For applications providing full keystroke services for newly created 
sessions, the Post Status Code service must be issued after every Read 
Input function to provide full compatibility with the workstation 
program. The use of all three status codes listed above at the correct 
times allows for proper operation of the keyboard services and autokey. 
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° 
/ 


° 
, 


PSRETNCD 


DB O . : 
PSFXNID DB O ; 
PSSESSID DB 0 ? 
PSRESERV DB 0O ; 
PSTASKID DW 0O : 
PSRETCOD DB 0 ; 


/ 


e 
’ 


° 
i 


. 
’ 
. 
Ul 


° 
f 


PARAMETER LIST FOR POST STATUS CODE 


INITIALIZE PARAMETER LIST FOR POST 


MOV PSRETNCD,OOH : 
MOV PSFXNID,OOH : 
MOV AL,SESSID ; 
MOV PSSESSID,AL 
MOV AX,TASKID ; 
MOV PSTASKID,AX 
MOV AL,RETCODE ; 
MOV PSRETCOD,AL 


RETURN CODE 

FUNCTION NUMBER 

SESSION ID 

RESERVED 

CONNECTOR'S TASK ID 
RETURN CODE TO BE POSTED 


STATUS CODE 


RETURN CODE MUST O BEFORE REQUEST 
FUNCTION ID MUST QO BEFORE REQUEST 
SESSION ID INTO THE LIST 


CONNECTOR'S TASK ID INTO THE LIST 


RETURN CODE INTO THE LIST 


INITIALIZE REGISTERS FOR POST STATUS CODE 


MOV AH,0O9H 

MOV AL,O7H 

MOV BH,80H 

MOV BL,20H 

MOV CX,OFFH 

MOV DX,KEYBOARD : 
MOV DI, SEG PSRETNCD~ ; 
MOV ES,DI ; 
MOV DI,OFFSET PSRETNCD ; 


RESOLVED VALUE FOR 'KEYBOARD' 
SEGMENT ADDRESS OF PARAMETER LIST 
IN ES 

OFFSET OF PARAMETER LIST IN DI 


SIGNAL WORKSTATION PROGRAM FOR POST STATUS CODE SERVICE 


INT 7AH 
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Introduction 


Introduction 


This chapter describes how to code requests for the window management 
services provided by the API. 


The window management services allow your application program to use 
the functions of the work station control session of the IBM 3270 Personal 
Computer. Using these services, your application program can determine 
the current size, position, or color of a window, and change them if desired. 
You can jump to specified windows, enlarge or hide windows, or change to 
a different screen profile. You can add a window, delete a window, or clear 
the entire screen. 


Your application program must request the Connect to Work Station 
Control service before it can request any of the other window management 
services. After the Connect to Work Station Control service has been 
completed successfully, the keyboard is attached to the work station control 
session and the operator information area (OJA) is displayed on the bottom 
line of the screen, with the following symbols: 


e WSCTRL 

e viz x clock (X [ ] on non-3270 PC hardware) 
e WINDOW = name 

e SCREEN =number 


Note: When using work station control API with non-8270 PC 
hardware, the WS Cirl OIA will not be displayed on either a 
Uni-DOS or Multi-DOS system under the following conditions: 


— Your application uses graphics mode 
— Your application uses 40-column mode 
— Your application writes directly to the screen. 


When your application program is finished using the window 
management services, it must request the Disconnect from Work Station 
Control service. If an error occurs during the execution of an 
application program that has connected to the work station control 
session, the OIA remains visible and the keyboard remains attached to 
the work station control session. You can press the Quit key (Alt plus 
Reset) to force termination of the connection to the work station 
control session. The program that was connected to the work station 
control session will continue to run, but any window management 
service requests that it makes will fail with an error code indicating 
that the program is not connected to the work station control session. 


Introduction 


Possible problems can occur by the simultaneous use of the keyboard 
service requests to connect to the work station control keyboard and 
the use of the window management service requests. 


— Ifthe keyboard for the work station control session is redirected to 
another session, the use of the Quit key to force termination of the 
connection to the work station control session for window 
management services will be lost. 


— If keystrokes are sent to the work station control session while 
window management service requests are being made, those 
keystrokes will effectively be lost except for the Quit key, which 
will terminate the connection to the work station control session for 
window management services. 


The window management services provided by the API are: 


— Connect to Work Station Control Service: Use this service to 
connect to the work station control session, to be able to use the 
window management services. 


— Disconnect from Work Station Control Service: Use this 
service to disconnect from the work station control session. 


— Add Window Service: Use this service to add a window from 
screen profile 0 to the specified screen profile. 


— Change Window Position on Screen Service: Use this service 
to change the position of a window on the specified screen profile. 
The window’s new position is determined by placing the upper left 
corner of the window at the specified row and column numbers. 


— Change Window Size Service: Use this service to change the 
size of a window on the specified screen profile. The window’s new 
size is determined by the specified number of rows and columns. 


— Change Window Color Service: Use this service to change the 
foreground and background colors of a window on the specified 
screen profile. 


— Change Window Position on Presentation Space Service: Use 
this service to change the position of a window on the presentation 
space for the specified screen profile. The window’s new position is 
determined by placing the upper left corner of the window at the 
specified row and column numbers. 


~ Change Hidden State Service: Use this service to toggle the 
“hidden” state of a window on the specified screen profile. A hidden 
window becomes not hidden, or a window that is not hidden 
becomes hidden. 
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Change Enlarge State Service: Use this service to toggle the 
“enlarge” state of the display image. An enlarged display image 
becomes normal, or a normal display image becomes enlarged. 


Change Screen Background Service: Use this service to 
change the background color of the specified screen profile. 


Query Window Position on Screen Service: Use this service to 
obtain the position of a window on the specified screen profile. The 
window’s position is given by the row and column numbers of the 
upper left corner of the window. 


Query Window Size Service: Use this service to obtain the size 
of a window on the specified screen profile. The window’s size is 
given as the number of rows and columns in the window. 


Query Window Colors Service: Use this service to obtain the 
foreground and background colors of a window on the specified 
screen profile. 


Query Window Position on Presentation Space Service: Use 
this service to obtain the position of a window on the specified 
screen profile. The window’s position is given by the row and 
columns of the upper left corner of the window. 


Query Hidden State Service: Use this service to obtain the 
“hidden” state of a window on the specified profile. The hidden 
state tells whether the window is hidden or not hidden. 


Query Enlarge State Service: Use this service to obtain the 
“enlarge” state of the display image. The display image can be 
either enlarged or not enlarged. In an enlarged image, the active 
window is displayed on the entire screen. 


Query Screen Background Color Service: Use this service to 
obtain the background color of the specified screen profile. 


Query Window Names Service: Use this service to obtain the 
short names of all windows in the specified screen profile. 


Clear Screen Service: Use this service to delete all windows 
from the specified screen profile. Windows cannot be deleted from 
screen profile 0. 


Select Active Window Service: Use this service to select a 
window on the specified screen profile to become the active window. 


Redraw Screen Service: Use this service to redraw the specified 
screen profile, if it is the active screen. 


Redraw Window Service: Use this service to redraw a window 
on the specified screen profile, if it is the active screen. 
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Delete Window Service: Use this service to delete a window 
from the specified screen profile. Windows cannot be deleted from 
screen profile 0. 


Query Active Window Service: Use this service to obtain the 
short name of the active window in the specified screen profile. 


Query Active Screen Service: Use this service to obtain the 
number of the active screen profile. 


Query Window Attributes Service: Use this service to obtain 
the following information about a window on the specified screen 
profile: 


— Number of rows and columns in the window 

— Row and column number of the upper left corner of the window 
on the screen 

— Window colors and border colors 

— Control flags 

— Row and column number of the upper left corner of the window 
on the presentation space. 


Change Window Attributes Service: Use this service to change 
the following information about a window on the specified screen 
profile: 


— Number of rows and columns in the window 

— Row and column number of the upper left corner of the window 
on the screen 

— Window colors and border colors 

— Control flags . 

— Row and column number of the upper left corner of the window 
on the presentation space. 


Select Active Screen Service: Use this service to make active 
the specified screen profile. 


Requesting the Window Management Services 


To request any of the window management services, load the registers and 
the parameter list with the proper values, and use the INT 7AH instruction 
to signal the workstation program that it has a request to process. 


Note: 


Before your application can request the window management services, 
it must request the Name Resolution service, using ‘WSCTRL ’ as 
the gate name in the parameter list. (Remember that the gate name 
must be padded to the right with blanks if it is less than eight 


characters.) 


Chapter 6. Coding Window Management Service Requests 6-5 


Introduction 


Return Codes for the Window Management Services 


Each window management service has two return codes associated with it: 
a system return code and a window management return code. Both types of 
return codes are two-byte values made up of a function ID and an error 
number. The function ID indicates the portion of the workstation program 
in which the error occurred. The error number indicates the specific type 
of error that has occurred. An error number of X‘00’ always indicates a 
successful acceptance or completion of the request. 


e System Return Codes: 


After your application has requested a window management service, the 
CH and CL registers contain a return code generated by the request 
processing portion of the workstation program. The function ID is in 
the CH register, and the error number is in the CL register. System 
return codes use a function ID of X‘12’. The error codes that can 
appear are: 


Code Meaning 


X‘00’ Request accepted. 

X‘05’ Invalid index specified. 
X‘07’ Invalid reply specified. 
X‘08’ Invalid wait type specified. 
X‘0B’ RQE pool depleted. 

X‘OF’ Invalid environment access. 
X‘34’ ~=—ssInvalid gate entry. 


These system return codes apply to all window management services. 
e Window Management Services Return Codes: 


After a requested window management service is completed, bytes 0 and 
1 of the parameter list contain a return code generated by the window 
management portion of the workstation program. The function ID is in 
byte 1, and the error number is in byte 0. Window management return 
codes use a function ID of X‘63’. The error numbers that can appear are 
specific to the service that was requested and are included in the 
descriptions of each service. 


See Appendix H, “Return Codes,” for more information. 
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Connect to Work Station Control 


Window Management Service X‘01’: Connect to Work 
Station Control 


Use this service to connect to the work station control session, to be able to 
use the window management services. 


Register Values 


On Request On Completion 

AH = X‘09’ CH = X‘12’ 

AL = X‘01’ CL = Return code 

BH = X‘80’ 

BL = X‘20’ The contents of registers 
CX = X‘O0OFF’ AX, BX, DX, ES, and DI 
DX = Resolved value for WSCTRL are unpredictable. 


ES = Segment address of the parameter list 
DI = Offset address of the parameter list 


| Contents Contents 
Offset | Length on Request on Completion 
fo [1 byte 


i Function 1D O68) 
Unchanged 


Parameter Definitions 
Request Parameters: 


e The session ID is the ID of the session requesting the use of the window 
management services. 


Return Codes 
e System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 
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Window Management Services Return Codes: 

Bytes 0 and 1 of the parameter list contain a return code generated by 

the window management portion of the workstation program. The 

function ID is in byte 1, and the error number is in byte 0. Window 

management return codes use a function ID of X‘63’. The error codes 

that can be received for this service are: 

Code Meaning 

X‘00’ Successful completion. 

X‘02’ Invalid session ID. 

X ‘04’ A session is already connected for window management 
services. 

X‘0C’ Byte 0 of the parameter list is not zero on request. 


See Appendix H, “Return Codes,” for more information. 


Only one session can be connected for window management services at 
a time. 


When the connection is completed, the following symbols will appear in 
the operator information area (OIA): 


— WSCTRL 

— viz X CLOCK (X [ ] on non-3270 PC hardware) 
— WINDOW =name 

— SCREEN =number 


~— When using work station control API with non-3270 PC hardware, 
the WS Ctrl OIA will not be displayed on either a Uni-DOS or 
Multi-DOS system under the following conditions: 


— Your application uses graphics mode 
— Your application uses 40-column mode 
— Your application writes directly to the screen. 


— While your application program is using the window management 
services, the screen and windows are not redrawn. The screen is 
redrawn when your application requests the Disconnect from Work 
Station Control service. In order to update the display screen while 
connected to the work station control session, your application 
must request either the Redraw Screen service or the Redraw 
Window service. 


Connect to Work Station Control 


While a session is connected to the work station control session, the 
keyboard belongs to the work station control session. All 
keystrokes typed at the keyboard are rejected except the Quit key, 
unless your application program has issued a Connect to Keyboard 
service request to the work station control session to intercept 
keystrokes. In this case, the keystrokes will be sent to your 
application program instead of to the work station control session. 


The Quit key allows the user to disconnect from the work station 
control session at any time. The Quit key can be used to enable the 
keyboard in the event that an application program finishes without 
disconnecting from the work station control session. When the Quit 
key is pressed, the application program is disconnected from the 
work station control session. Keystrokes typed at the keyboard are 
directed either to the active window, or to the work station control 
session if no windows exist on the active screen. 


Note: The Quit key is active once your application program issues a 
Connect to Work Station Control service request. If the Quit 
key is pressed while the application program is running, any 
subsequent requests to window management services 
(including the Disconnect from Work Station Control service) 
fail with a return code indicating that the session is not 
connected to the work station control session. 


If your application program hangs, because of a problem in the 
application, the usual recovery sequence of pressing the Ctr]-Alt-Del 
keys causes a re-IPL of the entire workstation program. To recover 
only the session in which the faulty application program is running, 
you must first disconnect from the work station control session by 
the Quit key. Once the Quit key is pressed, the Ctrl-Alt-Del 
keystroke sequence re-IPLs the session without disrupting the rest 
of the sessions that are running. 
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Coding Example 


° 
1 


+ PARAMETER LIST FOR CONNECT TO WORK STATION CONTROL 


RETURN CODE 
FUNCTION NUMBER 
SESSION ID 


CWRETNCD DB 0O 
CWFXNID DB 0O 
CWSESSID DB 0 


me Se Ne 


INITIALIZE PARAMETER LIST FOR CONNECT TO WORK STATION CONTROL 


se me Ne 


MOV CWRETNCD , OOH ; RETURN CODE MUST QO BEFORE REQUEST 
MOV CWFXNID,OOH ; FUNCTION ID MUST QO BEFORE REQUEST 
MOV AL, SESSION ; SESSION ID INTO PARAMETER LIST 

MOV CWSESSID,AL 


; INITIALIZE REGISTERS FOR CONNECT TO WORK STATION CONTROL 


MOV AH ,O9H 

MOV AL,0O1H 

MOV BH, 80H 

MOV BL, 20H 

MOV CX, OF FH 

MOV DX ,WSCTRL ; RESOLVED VALUE FOR 'WSCTRL ' 

MOV DI, SEG CWRETNCD ; SEGMENT ADDRESS OF PARAMETER LIST 
MOV ES,DI ; IN ES 

MOV DI,OFFSET CWRETNCD ; OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR CONNECT TO WORK STATION CONTROL SERVICE 
; 


INT 7AH 
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Disconnect from Work Station Control 


Window Management Service X‘02’: Disconnect from 
Work Station Control 


Use this service to disconnect from the work station control session. 


Register Values 


On Request On Completion 

AH = X‘09’ CH = X‘12’ 

AL = X‘02’ CL = Return code 

BH = X‘80’ 

BL = X‘20’ The contents of registers 
CX = X‘0O0FF’ AX, BX, DX, ES, and DI 
DX = Resolved value for WSCTRL are unpredictable. 

ES = Segment address of the parameter list 


DI Offset address of the parameter list 


Parameter List Format 


Contents Contents 
Offset | Length on Request on Completion 
1 byte 


Function ID (63) 
Unchanged 


Parameter Definitions 
Request Parameters: 


e The session ID is the ID of the session currently connected to the work 
station control session. 


Chapter 6. Coding Window Management Service Requests 6-11 


Disconnect from Work Station Control 


Return Codes 
e System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


e Window Management Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the window management portion of the workstation program. The 
function ID is in byte 1, and the error number is in byte 0. Window 
management return codes use a function ID of X‘63’. The error codes 
that can be received for this service are: 


Code Meaning 


X‘00’ Successful completion. 

X‘04’ The session is not connected for window management 
services. 

X‘0C’ Byte 0 of the parameter list is not zero on request. 


See Appendix H, “Return Codes,” for more information. 


Usage Notes 
@ When the disconnect is completed, the following occurs: 
— The screen is redrawn. 


— The work station control OIA is removed from the screen, and 
keystrokes typed on the keyboard are directed to the active window. 


— If there are no windows on the active screen: 


— On 3270 PC hardware, the work station control OIA remains on 
the screen, 


— On non-3270 PC hardware, the work station control OIA appears 


on the screen. The prompt “Valid Keys: WSCTRL List Print A-Z 
0-9 Jump ChgSc Quit” will appear. 
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Disconnect from Work Station Control 


Coding Example 


i 


; PARAMETER LIST FOR DISCONNECT FROM WORK STATION CONTROL 


DWRETNCD DB 0 ; RETURN CODE 


DWFXNID DB: «0 ; FUNCTION ID 
DWSESSID DB 0 ; SESSION ID 


; INITIALIZE PARAMETER LIST FOR DISCONNECT FROM WORK STATION CONTROL 
; 
MOV DWRETNCD, OOH 
MOV DWFXNID, OOH 
MOV AL,SESSID 
MOV DWSESSID,AL 


RETURN CODE MUST = O BEFORE REQUEST 
FUNCTION ID MUST = O BEFORE REQUEST 
SESSION ID OBTAINED FROM REQUEST 

TO QUERY SESSION ID SERVICE 


 —e “oe =e Ne 


; INITIALIZE REGISTERS FOR DISCONNECT FROM WORK STATION CONTROL 


MOV AH ,O9H 

MOV AL ,O2H 

MOV BH , 80H 

MOV BL, 20H .. 

MOV CX, OFFH 

MOV DX,WSCTRL ; RESOLVED VALUE FOR 'WSCTRL' 

MOV DI, SEG DWRETNCD ; SEGMENT ADDRESS OF PARAMETER LIST 

MOV ES,DI ? INES 

MOV DI,OFFSET DWRETNCD ; OFFSET OF PARAMETER LIST IN DI 
; SIGNAL WORKSTATION PROGRAM FOR DISCONNECT FROM WORK STATION CONTROL 
; SERVICE 
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Window Management Service X‘03’: Add Window 


Use this service to add a window from screen profile 0 to the specified 
screen profile. 


Register Values 


On Request On Completion 

AH = X‘09’ CH = X‘12’ 

AL = X‘03’ CL = Return code 

BH = X‘80’ 

BL = X‘20’ The contents of registers 
CX = X‘00FF’ AX, BX, DX, ES, and DI 
DX = Resolved value for WSCTRL are unpredictable. 

ES = Segment address of the parameter list 

DI = Offset address of the parameter list 


Parameter List Format 


Contents Contents 
on Request on Completion 
OA byte 


1 1 byte Must be zero Function ID 
(X‘63’) 


Unchanged 


3 1 byte Screen profile Unchanged 
number 

4 1 byte . Window short Unchanged 
name 


Parameter Definitions 


Request Parameters: 


e The session ID is the ID of the session currently connected to the work 
station control session. 


e The screen profile number is the number (in ASCID of the screen profile 
that you are adding the window to. Windows cannot be added to screen 
profile 0. 


e The window short name is the 1-character ASCII name for the window 


being added. Window short names must be alphabetic characters (A 
through Z). 
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Return Codes 


Add Window 


e System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


e Window Management Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the window management portion of the workstation program. The 
function ID is in byte 1, and the error number is in byte 0. Window 
management return codes use a function ID of X‘63’. The error codes 
that can be received for this service are: 


Code 


X‘00’ 
X‘01’ 


X ‘02’ 
X04’ 


X‘05’ 
X‘06’ 
X‘09° 
X‘0C’ 


Meaning 


Successful completion. 

The maximum number of windows has already been reached 
(no free WCBs). 

Invalid session ID. 

The session is not connected for window management 
services. 

The window already exists on screen. 

Invalid screen ID. 

The window is not on screen 0. 

Byte 0 of the parameter list is not zero on request. 


See Appendix H, “Return Codes,” for more information. 


Usage Notes 


e The added window becomes the active window. 


e Windows cannot be added to screen profile 0. 
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° 
, 


° 
, 


PARAMETER LIST FOR ADD WINDOW 


AWRETNCD DB 
AWFXNID DB 
AWSESSID DB 
AWSCRPRO DB 
AWWINDN DB 


° 
f 


. 
1 


. 
f 
° 
! 


e 
, 


oOoo000 


=e se Se Se Ne 


RETURN CODE 

FUNCTION ID 

SESSION ID 

SCREEN PROFILE NUMBER IN ASCII 
WINDOW SHORT NAME IN ASCII 


INITIALIZE PARAMETER LIST FOR ADD WINDOW 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


AWRETNCD, 00H 
AWFXNID ,00H 
AL,SESSID 
AWSESSID,AL 
AG,2 14 
AWSCRPRO, AL 
AL, 'P! 
AWWINDN ,AL 


aS ll Bl Sl it ST Bi! | 


RETURN CODE MUST 
FUNCTION ID MUST 
SESSION ID 

IN PARAMETER LIST 
SCREEN PROFILE NUMBER 1 
IN PARAMETER LIST 
WINDOW SHORT NAME 'P' 
IN PARAMETER LIST 


QO BEFORE REQUEST 
O BEFORE REQUEST 


INITIALIZE REGISTERS FOR ADD WINDOW 


MOV 
MOV 
- MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


AH ,O9H 

AL,03H 

BH, 80H 

BL,20H 

CX, OF FH 

DX ,WSCTRL 

DI, SEG AWRETNCD 
ES,DI 

DI,OFFSET AWRETNCD 


e 
f 
° 
f 
° 
‘ 
f 


SIGNAL WORKSTATION PROGRAM FOR ADD 


INT 


7AH 


RESOLVED VALUE FOR 'WSCTRL' 
SEGMENT ADDRESS OF PARAMETER LIST 
IN ES 

OFFSET OF PARAMETER LIST IN DI 


WINDOW SERVICE 


Change Window Position on Screen 


Window Management Service X‘04’: Change Window 
Position on Screen 


Register Values 


Use this service to change the position of a window on the specified screen 
profile. The window’s new position is determined by placing the upper left 
corner of the window at the row and column numbers specified in the 
parameter list. 


On Request On Completion 

AH = X‘09’ CH = X‘12’ 

AL = X‘04 CL = Return code 

BH = X‘80’ 

BL = X‘20’ The contents of registers 
CX = X‘00FF’ AX, BX, DX, ES, and DI 
DX = Resolved value for WSCTRL are unpredictable. 

ES Segment address of the parameter list 


Offset address of the parameter list 


Contents Contents 
Offset Length on Request on Completion 


Te 


1 1 byte Must be zero Function ID 
(X‘63’) 


3 1 byte Screen profile Unchanged 
number 
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Request Parameters: 


The session ID is the ID of the session currently connected to the work 
station control session. 


The screen profile number is the number (in ASCII) of the screen profile 
containing the specified window. 


The window short name is the 1-character ASCII name for the window 
being changed. Window short names must be alphabetic characters. 


“Row” is the new row position for the upper left corner of the window 
on the screen. 


“Column” is the new column position for the upper left corner of the 
window on the screen. 


Note: Row and column numbers start at zero. 


Completion Parameters: 


“Row” is the row number chosen by the workstation program when the 
row number in the parameter list on request caused the window to 
overlap the screen boundaries. 


“Column” is the column number chosen by the workstation program 
when the column number in the parameter list on request caused the 
window to overlap the screen boundaries. 


Note: Row and column numbers start at zero. 


Return Codes 


Change Window Position on Screen 


e System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


e Window Management Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the window management portion of the workstation program. The 
function ID is in byte 1, and the error number is in byte 0. Window 
management return codes use a function ID of X‘63’. The error codes 
that can be received for this service are: 


Code 


X00’ 
X‘02’ 
X‘04’ 


X‘06’ 
X‘07’ 
X‘0C’ 
X‘0ER’ 
X‘10" 


Meaning 


Successful completion. 

Invalid session ID. 

The session is not connected for window management 
services. 

Invalid screen ID. 

The window was not found on screen. 

Byte 0 of the parameter list is not zero on request. 

No windows exist on screen. 

The window overlapped the screen boundaries or did not fit 
on the screen. 


See Appendix H, “Return Codes,” for more information. 


Usage Notes 


e Ifthe window overlaps the screen boundaries after it has been moved to 
the new position: 


— The window is moved to fit on the screen. 


— A return code of X‘10’ is returned in the parameter list. 


— The row and column numbers of the window position chosen by the 
workstation program are returned in the parameter list. 


Chapter 6. Coding Window Management Service Requests 6-19 


Change Window Position on Screen 


Coding Example 


6-20 


i 


; PARAMETER LIST FOR CHANGE WINDOW 


CSRETNCD 
CSFXNID 
CSSESSID 
CSSCREEN 
CSWINDOW 
CSROW 


CSCOLUMN 


DB 
DB 
DB 
DB 
DB 
DB 


DB 


oO Oo0000 


pT ST Bal ST Ml aT Mt TY 


POSITION ON SCREEN 


RETURN CODE 

FUNCTION NUMBER 

SESSION ID 

SCREEN PROFILE NUMBER 

WINDOW SHORT NAME 

ROW POSITION OF UPPER LEFT CORNER 
OF WINDOW 

COLUMN POSITION OF UPPER LEFT 
CORNER OF WINDOW 


; INITIALIZE PARAMETER LIST FOR CHANGE WINDOW POSITION ON SCREEN 


e 
’ 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


CSRETNCD , 00H ; 
CSFXNID, OOH ; 
AL,SESSID : 
CSSESSID,AL 
CSSCREEN,'2' 
CSWINDOW,'B' 
AL ,ROW 
CSROW, AL 

AL ,COL 
CSCOLUMN , AL 


~e we Ne 


~e 


RETURN CODE MUST = O BEFORE REQUEST 
FUNCTION ID MUST = 0 BEFORE REQUEST 
SESSION ID INTO THE LIST 


SCREEN NUMBER 2 
WINDOW 'B' SHORT NAME 
ROW POSITION INTO THE LIST 


COLUMN POSITION INTO THE LIST 


; INITIALIZE REGISTERS FOR CHANGE WINDOW POSITION ON SCREEN 


. 
‘ 


e 
’ 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


AH ,09H 

AL ,04H 

BH, 80H 

BL, 20H 

CX, OF FH 

DX ,WSCTRL : 
DI, SEG CSRETNCD ; 
ES ,DI ; 
DI,OFFSET CSRETNCD ; 


RESOLVED VALUE FOR 'WSCTRL' 
SEGMENT ADDRESS OF PARAMETER LIST 
IN ES 

OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR CHANGE WINDOW POSITION ON SCREEN SERVICE 


° 
a 


INT 


7AH 


Change Window Size 


Window Management Service X‘05’: Change Window Size 


Use this service to change the size of a window on the specified screen 
profile. The window’s new size is determined by the number of rows and 
columns specified in the parameter list. 


Register Values 


On Request On Completion 

AH = X‘09’ CH = X‘12’ 

AL = X‘08’ CL = Return code 

BH = X‘80’ 

BL = X‘20’ The contents of registers 
CX = X‘O0FF’ AX, BX, DX, ES, and DI 
DX = Resolved value for WSCTRL are unpredictable. 

ES = Segment address of the parameter list 

DI = Offset address of the parameter list 


Parameter List Format 


Contents Contents 
Offset Length on Request on Completion 


jo A byte 


Unchanged 
name 
5 1 byte Rows Unchanged, or 
rows 
1 byte Columns Unchanged, or 
columns 


Parameter Definitions 


Request Parameters: 


e The session ID is the ID of the session currently connected to the work 
station control session. 


e The screen profile number is the number (in ASCII) of the screen profile 
containing the specified window. 


e The window short name is the 1-character ASCII name for the window 
being changed. Window short names must be alphabetic characters. 
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“Rows” is the number of rows in the new window size. 


“Columns” is the number of columns in the new window size. 


Completion Parameters: 


“Rows” is the number of rows chosen by the workstation program when 
the number of rows in the parameter list on request caused the window 
to become too big to fit on the screen or the presentation space. 


“Columns” is the number of columns chosen by the workstation 
program when the number of columns in the parameter list on request 
caused the window to become too big to fit on the screen or the 
presentation space. 


System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


_ Window Management Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the window management portion of the workstation program. The 
function ID is in byte 1, and the error number is in byte 0. Window 
management return codes use a function ID of X‘63’. The error codes 
that can be received for this service are: 


Code Meaning 


X‘00’ Successful completion. 

X‘02’ Invalid session ID. 

X‘04’ The session is not connected for window management 
services. 

X‘06’ Invalid screen ID. 

X‘07’ The window was not found on screen. 

X‘0C’ Byte 0 of the parameter list is not zero on request. 

X‘0E’ No windows exist on the screen. 

X‘10" The window overlapped the screen boundaries or did not fit 


on the screen, because of the row and column values sent in 
the parameter list. If the window size was too big, the 
number of rows and columns chosen by the workstation 
program is returned in the parameter list. 


See Appendix H, “Return Codes,” for more information. 


Change Window Size 


Usage Notes 
e A value of 0 for either the number of rows or the number of columns in 
the window size is changed by the workstation program to be a value of 


1. 


e Ifthe window overlaps the screen boundaries after it has been changed 
to the new size: 


— The window is moved to fit on the screen. 
— A return code of X‘10’ is returned in the parameter list. 


e Ifthe window overlaps the presentation space boundaries after it has 
been changed to the new size: 


— The window is moved to fit on the presentation space. 
—- A return code of X‘10’ is returned in the parameter list. 


e If the window is too big to fit on the screen or the presentation space 
after it has been changed to the new size: 


— The window size is reduced, and the window position is changed (if 
necessary), to allow the window to fit on the screen and the 
presentation space. 


— A return code of X‘10’ is returned in the parameter list. 


— The number of rows and columns in the window size chosen by the 
workstation program is returned in the parameter list. 
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° 
/ 


; PARAMETER LIST FOR CHANGE WINDOW 


CZRETNCD 
CZFXNID 

CZSESSID 
CZSCRPRO 
CZWINDN 

CZNUMROW 
CZNUMCOL 


. 
, 


. 
’ 


. 
t 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


OO00000 


CZRETNCD, 00H 
CZFXNID, OOH 
AL,SESSID 
CZSESSID,AL 
AL, 1! 
CZSCRPRO,AL 
AL,'P! 
CZWINDN, AL 
AL,10 
CZNUMROW, AL 
AL,15 
CZNUMCOL , AL 


SIZE 


=e “Se Se Se Me Ne Ne 


ST a il MT ee ST eT MT eT eT YY 


RETURN CODE 
FUNCTION ID 

SESSION ID 

SCREEN PROFILE NUMBER IN ASCII 
WINDOW SHORT NAME IN ASCII 

NUMBER OF ROWS IN NEW WINDOW SIZE 
NUMBER OF COLUMNS IN NEW WINDOW SIZE 


INITIALIZE PARAMETER LIST FOR CHANGE WINDOW SIZE 


RETURN CODE MUST O BEFORE REQUEST 
FUNCTION ID MUST QO BEFORE REQUEST 
SESSION ID OBTAINED FROM REQUEST 

TO QUERY SESSION ID 

SCREEN PROFILE NUMBER 1 

IN PARAMETER LIST 

WINDOW SHORT NAME 'P' 

IN PARAMETER LIST 

NUMBER OF ROWS IN THE NEW 

WINDOW SIZE 

NUMBER OF COLUMNS IN THE 

WINDOW SIZE 


; INITIALIZE REGISTERS FOR CHANGE WINDOW SIZE 


. 
f 


° 
f 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


AH ,O9H 

AL ,O5H 

BH, 80H 

BL ,20H 

CX, OFFH 

DX , WSCTRL 

DI, SEG CZRETNCD 
ES ,DI 

DI,OFFSET CZRETNCD 


e 
‘ 
. 
f 
‘ 
. 
‘ 


RESOLVED VALUE FOR 'WSCTRL' 
SEGMENT ADDRESS OF PARAMETER LIST 
IN ES 

OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR CHANGE WINDOW SIZE SERVICE 


. 
, 


INT 


7AH 


Change Window Color 


Window Management Service X‘06’: Change Window 


Color 


Register Values 


Use this service to change the foreground and background colors of a 
window on the specified screen profile. 


On Request On Completion 

AH = X‘09’ CH = X‘12’ 

AL = X‘06’ CL = Return code 

BH = X‘80’ 

BL = X‘20’ The contents of registers 
CX = X‘O0FF’ AX, BX, DX, ES, and DI 
DX = Resolved value for WSCTRL are unpredictable. 

ES = Segment address of the parameter list 

DI = Offset address of the parameter list 


Parameter List Format 


Contents Contents 
Offset Length on Request on Completion 


1 byte 


1 byte Must be zero Function ID 
(X‘63’) 


3 1 byte Screen profile Unchanged 
number 


4 1 byte Window short Unchanged 
name | 
1 byte Foreground color Unchanged 
value 
1 byte Background color | Unchanged 
value 
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Change Window Color 


Parameter Definitions 
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Request Parameters: 


The session ID is the ID of the session currently connected to the work 
station control session. 


The screen profile number is the number (in ASCII) of the screen profile 
containing the specified window. 


The window short name is the 1-character ASCII name for the window 
being changed. Window short names must be alphabetic characters. 


The foreground and background color values are as follows: 
Value Color 


Black 
Blue 

Red 

Pink 
Green 
Turquoise 
Yellow 
White 


ARO WNHO 
tot uo te we we weal 


If the foreground or background color value is greater than 7, the color 
value is selected using the formula: color=value MOD 8. 


The base color is specified as follows: 


— A value of 1 indicates that the base colors are to be used to display 
the window. 

— A value other than 1 indicates that the specified foreground and 
background colors are to be used to display the window. 


Note: Setting base colors for the window overrides the color values 
specified for the foreground and background. 


Return Codes 


Change Window Color 


System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


Window Management Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the window management portion of the workstation program. The 
function ID is in byte 1, and the error number is in byte 0. Window 
management return codes use a function ID of X‘63’. The error codes 
that can be received for this service are: 


Code 


X‘00’ 
X ‘02’ 
X‘04’ 
X‘06’ 
X ‘07’ 
X‘0C’ 
X‘OE’ 
X‘OF’ 
X‘12’ 


Meaning 


Successful completion. 

Invalid session ID. 

The session is not connected for window management services. 
Invalid screen ID. 

The window is not found on screen. 

Byte 0 of the parameter list is not zero on request. 

No windows exist on screen. 

No colors can be set for a PC session. 

Foreground and background colors are the same. The window 
name and the window border become black on white. 


See Appendix H, “Return Codes,” for more information. 
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Change Window Color 


Coding Example 
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. 
, 


; PARAMETER LIST FOR CHANGE WINDOW 


CCRETNCD 
CCFXNID 
CCSESSID 
CCSCREEN 
CCWINDOW 
CCFORGND 
CCBAKGND 
CCBASE 


° 
’ 


OO000000 


COLOR 


~e se Ne Ne Ne Ne Ne NO 


RETURN CODE 

FUNCTION NUMBER 
SESSION ID 

SCREEN PROFILE NUMBER 
WINDOW SHORT NAME 
FOREGROUND COLOR VALUE 
BACKGROUND COLOR VALUE 
BASE COLOR 


; INITIALIZE PARAMETER LIST FOR CHANGE WINDOW COLOR 


. 
f 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


CCRETNCD , 00H 
CCFXNID, 00H 
AL ,SESSID 
CCSESSID,AL 
CCSCREEN,'3! 
CCWINDOW,'S' 
CCFORGND , 4 
CCBAKGND , 0 
CCBASE , 0 


bt i i eT i eT eT TY 


RETURN CODE MUST = 0 BEFORE REQUEST 
FUNCTION ID MUST = O BEFORE REQUEST 
SESSION ID INTO PARAMETER LIST 


SCREEN NUMBER 3 
WINDOW 'S' SHORT NAME 
GREEN FOREGROUND 
BLACK BACKGROUND 

NO BASE COLORS 


; INITIALIZE REGISTERS FOR CHANGE WINDOW COLOR 


° 
' 


. 
t 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


AH, 09H 

AL, 06H 

BH, 80H 

BL, 20H 

CX, OF FH 

DX ,WSCTRL 

DI, SEG CCRETNCD 
ES,DI 

DI,OFFSET CCRETNCD 


° 
‘ 
e 
, 
° 
‘ 
, 


RESOLVED VALUE FOR 'WSCTRL  ' 
SEGMENT ADDRESS OF PARAMETER LIST 
IN ES 

OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR CHANGE WINDOW COLOR SERVICE 


° 
’ 


INT 


7AH 


Change Window Position on Presentation Space 


Window Management Service X‘07’: Change Window 
Position on Presentation Space 


Register Values 


Use this service to change the position of a window on the presentation 
space for the specified screen profile. The window’s new position is 
determined by placing the upper left corner of the window at the row and 
column numbers specified in the parameter list. 


On Request On Completion 

AH = X‘09’ CH = X‘12’ 

AL = X‘07’ CL = Return code 

BH = X‘80’ 

BL = X‘20’ The contents of registers 
CX = X‘00FF’ AX, BX, DX, ES, and DI 
DX = Resolved value for WSCTRL are unpredictable. 

ES = Segment address of the parameter list 


DI Offset address of the parameter list 


Parameter List Format 


Contents Contents 
Offset Length on Request on Completion 


1 byte 


1 1 byte Must be zero Function ID 
(X‘63’) 


1 byte Unchanged 

3 1 byte Screen profile Unchanged 
number 

4 1 byte Window short Unchanged 
name 

5 1 byte Row Unchanged, or 

row 
Column Unchanged, or 
column 


\ 
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Change Window Position on Presentation Space 


Parameter Definitions 
Request Parameters: 


e The session ID is the ID of the session currently connected to the work 
station control session. 


e The screen profile number is the number (in ASCII) of the screen profile 
containing the specified window. 


e The window short name is the 1-character ASCII name for the window 
being changed. Window short names must be alphabetic characters. 


e “Row” is the new row position for the upper left corner of the window 
on the presentation space. — 


e “Column” is the new column position for the upper left corner of the 
window on the presentation space. 


Note: Row and column numbers start at zero. 

Completion Parameters: 

e “Row” is the row number chosen by the workstation program when the 
row number in the parameter list on request caused the window to 
overlap the presentation space boundaries. 

e “Column” is the column number chosen by the workstation program 
when the column number in the parameter list on request caused the 


window to overlap the presentation space boundaries. 


Note: Row and column numbers start at zero. 
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Return Codes 


Usage Notes 


Change Window Position on Presentation Space 


System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


Window Management Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the window management portion of the workstation program. The 
function ID is in byte 1, and the error number is in byte 0. Window 
management return codes use a function ID of X‘63’. The error codes 
that can be received for this service are: 


Code Meaning 


X‘00’ Successful completion. 

X ‘02’ Invalid session ID. 

X‘04’ - ~=The session is not connected for window management 
services. 

X‘06’ Invalid screen ID. 

X‘07’ The window is not found on screen. 

X‘0C’ Byte 0 of the parameter list is not zero on request. 

X ‘OE’ No windows exist on screen. 

X‘10’ The window overlapped the presentation space boundaries or 


did not fit on the presentation space. 


See Appendix H, “Return Codes,” for more information. 


If the window overlaps the presentation space boundaries after it has 
been moved to the new position: 


— The window is moved to fit on the presentation space. 
— A return code of X‘10’ is returned in the parameter list. 


— The row and column numbers of the window position chosen by the 
workstation program are returned in the parameter list. 


This service accepts only row and column positions as parameters, not 
PEL positions such as those used by windows in graphics mode. 


This service is similar to the Browse function on the keyboard. When 
the window becomes the top window of the screen and the screen is 
active, if the cursor is not within the area shown by the window, the 
window will be moved on the presentation space until the cursor is 
within the window area. 
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Change Window Position on Presentation Space 


Coding Example 


« 
, 


; PARAMETER LIST FOR CHANGE WINDOW 


CPRETNCD 
CPFXNID 
CPSESSID 
CPSCRPRO 
CPWINDN 
CPROWNUM 


CPCOLNUM 


DB 
DB 
DB 
DB 
DB 
DB 


DB 


OO0O000 


jo) 


“eo Ne Me Ne Ne NO Se Ne Ne 


POSITION ON PRESENTATION SPACE 


RETURN CODE 

FUNCTION ID 

SESSION ID 

SCREEN PROFILE NUMBER IN ASCII 
WINDOW SHORT NAME IN ASCII 

ROW NUMBER FOR NEW POSITION OF 
UPPER LEFT CORNER OF WINDOW 
COLUMN NUMBER FOR NEW POSITION OF 
UPPER LEFT CORNER OF WINDOW 


; INITIALIZE PARAMETER LIST FOR CHANGE WINDOW POSITION ON PRESENTATION SPACE 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


CPRETNCD, 00H 
CPFXNID, OOH 
AL,SESSID 
CPSESSID,AL 
AL", 
CPSCRPRO,AL 
AL, 'P! 
CPWINDN , AL 
AL,20 
CPROWNUM , AL 
AL,25 
CPCOLNUM, AL 


Oat et et eT ee) eT et eT eT eT 


RETURN CODE MUST = O BEFORE REQUEST 
FUNCTION ID MUST = 0 BEFORE REQUEST 
SESSION ID OBTAINED FROM REQUEST 

TO QUERY SESSION ID SERVICE 

SCREEN PROFILE NUMBER 1 

IN PARAMETER LIST 

WINDOW SHORT NAME  'P' 

IN PARAMETER LIST 

ROW NUMBER FOR NEW POSITION OF 
UPPER LEFT CORNER OF WINDOW 

COLUMN NUMBER FOR NEW POSITION OF 
UPPER LEFT CORNER 


; INITIALIZE REGISTERS FOR CHANGE WINDOW POSITION ON PRESENTATION SPACE 


i iat iat 
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MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


INT 


AH,O9H 
AL,O7H 
BH, 80H 
BL,20H 
CX, OFFH 
DX ,WSCTRL : 
DI, SEG CPRETNCD ; 
ES,DI ; 
DI,OFFSET CPRETNCD ; 


7AH 


RESOLVED VALUE FOR WSCTRL 

SEGMENT ADDRESS OF PARAMETER LIST 
IN ES 

OFFSET OF PARAMETER LIST IN DI 


SIGNAL WORKSTATION PROGRAM FOR CHANGE WINDOW POSITION ON PRESENTATION 
SPACE SERVICE 


Change Hidden State 


Window Management Service X‘08’: Change Hidden 


State 


Register Values 


Use this service to toggle the “hidden” state of a window on the specified 
screen profile. (A hidden window becomes not hidden, or a window that is 
not hidden becomes hidden.) 


On Request On Completion 

AH = X‘09’ CH = X‘12’ 

AL = X‘08’ CL = Return code 

BH = X‘80’ 

BL = X‘20’ The contents of registers 
CX = X‘0O0FF’ AX, BX, DX, ES, and DI 
DX = Resolved value for WSCTRL are unpredictable. 


ES = Segment address of the parameter list 
DI = Offset address of the parameter list 


Parameter List Format 


Contents Contents 
Offset Length on Request on Completion 


1 byte 


1 1 byte Must be zero Function ID 
(X‘63’) 


Unchanged 


3 1 byte Screen profile Unchanged 
number 

4 1 byte Window short Unchanged 
name 


Parameter Definitions 


Request Parameters: 


e The session ID is the ID of the session currently connected to the work 
station control session. 


e The screen profile number is the number (in ASCII) of the screen profile 
containing the specified window. 


e The window short name is the 1-character ASCII name for the window 
being changed. Window short names must be alphabetic characters. 
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Change Hidden State 


Return Codes 


Usage Notes 
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e System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


e Window Management Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the window management portion of the workstation program. The 
function ID is in byte 1, and the error number is in byte 0. Window 
management return codes use a function ID of X‘63’. The error codes 
that can be received for this service are: 


Code Meaning 


X‘00’ Successful completion. 

X‘02’ Invalid session ID. 

X‘04’ The session is not connected for window management 
services. 

X‘06’ Invalid screen ID. 

X‘07’ The window is not found on screen. 

X‘0A’ Only one window on screen; the window cannot be hidden. 

X‘0B’ All other windows are hidden; the next window has been 
unhidden and made the active window. 

X‘0C’ Byte 0 of the parameter list is not zero on request. 

X‘0R’ No windows exist on screen. 


See Appendix H, “Return Codes,” for more information. 


e Ifthe requested window is the active window and all other windows are 
hidden, the next window on the screen profile becomes not hidden and 
is made the active window. 


Coding Example 


° 
’ 


; PARAMETER LIST FOR CHANGE HIDDEN 


CHRETNCD 
CHFXNID 

CHSESSID 
CHSCREEN 
CHWINDOW 


DB 
DB 
DB 
DB 
DB 


OO000 


me Ne Ne Ne Ne 


Change Hidden State 


STATE 


RETURN CODE 

FUNCTION NUMBER 
SESSION ID 

SCREEN PROFILE NUMBER 
WINDOW SHORT NAME 


; 
; INITIALIZE PARAMETER LIST FOR CHANGE HIDDEN STATE 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


CHRETNCD, OOH 
CHFXNID,0OOH 


AL,SESSID 


CHSESSID,AL 
CHSCREEN,'5' 
CHWINDOW,'T' 


Se i a aT eT 


RETURN CODE MUST = O BEFORE REQUEST 
FUNCTION ID MUST = 0 BEFORE REQUEST 


SESSION ID INTO THE 
PARAMETER LIST 

SCREEN NUMBER 5 
WINDOW 'T' SHORT NAME 


; INITIALIZE REGISTERS FOR CHANGE HIDDEN STATE 


me Se Ne 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


INT 


AH ,09H 

AL ,0O8H 
BH, 80H 
BL,20H 
CX , OFFH 
DX, WSCTRL 


ES,DI 


DI, SEG CHRETNCD ; 


DI,OFFSET CHRETNCD 


7AH 


RESOLVED VALUE FOR 'WSCTRL ' 
SEGMENT ADDRESS OF PARAMETER LIST 
IN ES 

OFFSET OF PARAMETER LIST IN DI 


SIGNAL WORKSTATION PROGRAM FOR CHANGE HIDDEN STATE SERVICE 
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Change Enlarge State 


Window Management Service X‘09’: Change Enlarge 


State 


Register Values 


Use this service to toggle the “enlarge” state of the display image. (An 
enlarged display image becomes normal, or a normal display image becomes 
enlarged.) 


On Request On Completion 

AH = X‘09’ CH = X‘12’ 

AL = X‘09’ CL = Return code 

BH = X‘80’ 

BL = X‘20’ The contents of registers 
CX = X‘0O0FF’ AX, BX, DX, ES, and DI 
DX = Resolved value for WSCTRL are unpredictable. 

ES = Segment address of the parameter list 


Offset address of the parameter list 


Contents Contents 
Offset Length on Request on Completion 


1 byte 


1 1 byte Must be zero Function ID 
(X‘63’) 


Session ID Unchanged 


Parameter Definitions 


Return Codes 
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Request Parameters: 


e The session ID is the ID of the session currently connected to the work 
station control session. 


e System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


Change Enlarge State 


Window Management Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the window management portion of the workstation program. The 
function ID is in byte 1, and the error number is in byte 0. Window 
management return codes use a function ID of X‘63’. The error codes 
that can be received for this service are: 


Code 
X‘00’ 
X‘02’ 
X‘04’ 


X‘0C’ 


Meaning 


Successful completion. 
Invalid session ID. 
The session is not connected for window management 


services. 


Byte 0 of the parameter list is not zero on request. 


See Appendix H, “Return Codes,” for more information. 


Coding Example 


° 
I 


; PARAMETER LIST FOR CHANGE ENLARGE STATE 


CERETNCD DB 0 
CEFXNID DB «0 
CESESSID DB 0 


RETURN CODE 
FUNCTION ID 
SESSION ID 


; INITIALIZE PARAMETER LIST FOR CHANGE ENLARGE STATE 


MOV 
MOV 
MOV 
MOV 


CERETNCD , OOH ; 
CEFXNID,00H ; 


AL,SESSID 


CESESSID,AL 


RETURN CODE MUST = O BEFORE REQUEST 
FUNCTION ID MUST = 0 BEFORE REQUEST 
SESSION ID OBTAINED FROM REQUEST 

TO QUERY SESSION ID SERVICE 


; INITIALIZE REGISTERS FOR CHANGE ENLARGE STATE 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


se Me Ne 


INT 


AH ,O9H 

AL ,0O9H 
BH, 80H 
BL, 20H 
CX, OF FH 
DX,WSCTRL 


ES,DI 
DI,OFFSET 


7AH 


DI, SEG CERETNCD ; 


CERETNCD 


RESOLVED VALUE FOR WSCTRL 

SEGMENT ADDRESS OF PARAMETER LIST 
IN ES |. 

OFFSET OF PARAMETER LIST IN DI 


SIGNAL WORKSTATION PROGRAM FOR CHANGE ENLARGE STATE SERVICE 
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Change Screen Background 


Window Management Service X‘0A’: Change Screen 
Background 


Use this service to change the background color of the specified screen 


profile. 
Register Values 
On Request * On Completion 
AH = X‘09’ CH = X‘12’ 
AL = X‘0A’ CL = Return code 
BH = X‘80’ 
BL = X‘20’ The contents of registers 
CX = X‘00FF’ AX, BX, DX, ES, and DI 
DX = Resolved value for WSCTRL are unpredictable. 


ES = Segment address of the parameter list 
DI = Offset address of the parameter list 


Parameter List Format 


Contents Contents 
Offset Length on Request on Completion 


1 byte 


it 1 byte Must be zero Function ID 
(X‘63’) 


3 1 byte Screen profile Unchanged 
number 

4 1 byte Screen Unchanged 
background color 


Parameter Definitions 


Request Parameters: 


e The session ID is the ID of the session currently connected to the work 
station control session. 


e The screen profile number is the number (in ASCII) of the screen profile 
being changed. 
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Change Screen Background 


e The background color values are as follows: 


Value 


NOP WNF © 


toi wt wt te he ue 


Color 


Black 
Blue 

Red 

Pink 
Green 
Turquoise 
Yellow 
White 


If the background color value is greater than 7, the color value is selected 
using the formula: color = value MOD 8. 


Return Codes 


e System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


e Window Management Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 


the window management portion of the workstation program. The 
function ID is in byte 1, and the error number is in byte 0. Window 


management return codes use a function ID of X‘63’. The error codes 
that can be received for this service are: 


Code 


X‘00’ 
X‘02’ 
X‘04’ 


X‘06’ 
X‘0C’ 


Meaning 


Successful completion. 

Invalid session ID. 

The session is not connected for window management 
services. 

Invalid screen ID. 

Byte 0 of the parameter list is not zero on request. 


See Appendix H, “Return Codes,” for more information. 
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Change Screen Background 


Coding Example 
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: 
, 


° 
f 


PARAMETER LIST FOR CHANGE SCREEN 


CBRETNCD DB 
CBFXNID DB 
CBSESSID DB 
CBSCREEN DB 
CBCOLOR DB 


. 
‘ 
° 
f 


. 
‘ 


’ 


° 
7 
. 
f 


° 
, 


OO000 


BACKGROUND 


eo Se Ne Ne NO 


RETURN CODE 

FUNCTION NUMBER 

SESSION ID 

SCREEN PROFILE NUMBER 
SCREEN BACKGROUND COLOR 


INITIALIZE PARAMETER LIST FOR CHANGE SCREEN BACKGROUND 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


CBRETNCD , OOH 
CBFXNID ,00H 
AL,SESSID 
CBSESSID,AL 
CBSCREEN,'0' 
CBCOLOR, 7 


=e Se Ne Ne NO Ne 


O BEFORE REQUEST 
O BEFORE REQUEST 


RETURN CODE MUST 
FUNCTION ID MUST 
SESSION ID INTO THE 
PARAMETER LIST 

SCREEN NUMBER 0 
BACKGROUND COLOR = WHITE 


INITIALIZE REGISTERS FOR CHANGE SCREEN BACKGROUND 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


AH , 09H 

AL , OAH 

BH, 80H 

BL, 20H 

CX, OFFH 

DX ,WSCTRL 

DI, SEG CBRETNCD 
ES,DI 

DI,OFFSET CBRETNCD 


° 
, 
. 
a 
e 
t 
. 
‘ 


RESOLVED VALUE FOR 'WSCTRL ' 
SEGMENT ADDRESS OF PARAMETER LIST 
IN ES 

OFFSET OF PARAMETER LIST IN DI 


SIGNAL WORKSTATION PROGRAM FOR CHANGE SCREEN BACKGROUND SERVICE 


INT 


7AH 


Query Window Position on Screen 


Window Management Service X‘0B’: Query Window 
Position on Screen 


Use this service to obtain the position of a window on the specified screen 
profile. The window’s position is given by the row and column numbers of 
the upper left corner of the window. 


Register Values 


On Request On Completion 

AH = X‘09’ CH = X‘12’ 

AL = X‘0B’ CL = Return code 

BH = X‘80’ 

BL = X‘20’ The contents of registers 
CX = X‘O0FF’ AX, BX, DX, ES, and DI 
DX = Resolved value for WSCTRL are unpredictable. 

ES = Segment address of the parameter list 

DI = Offset address of the parameter list 


Contents Contents 
on Request on Completion 


Must be zero Function ID 
(X‘63’) 


3 1 byte Screen profile Unchanged 
number 
4 1 byte Window short Unchanged 
~| name 


Reserved 
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Query Window Position on Screen 


Parameter Definitions 


Return Codes 
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Request Parameters: 


The session ID is the ID of the session currently connected to the work 
station control session. 


The screen profile number is the number (in ASCII) of the screen profile 
containing the specified window. 


The window short name is the 1-character ASCII name for the window 
being queried. Window short names must be alphabetic characters. 


Completion Parameters: 


“Row” is the row number of the upper left corner of the window on the 
screen. 


“Column” is the column number of the upper left corner of the window 
on the screen. 


System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


Window Management Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the window management portion of the workstation program. The 
function ID is in byte 1, and the error number is in byte 0. Window 
management return codes use a function ID of X‘63’. The error codes 
that can be received for this service are: 


Code Meaning 


X‘00° Successful completion. 

X‘02’ Invalid session ID. 

X‘04’ The session is not connected for window management 
services. 

X ‘06’ Invalid screen ID. 

X‘07" The window is not found on screen. 

X‘0C’ Byte 0 of the parameter list is not zero on request. 

X‘0ER’ No windows exist on screen. 


See Appendix H, “Return Codes,” for more information. 


Coding Example 


. 
t 


Query Window Position on Screen 


; PARAMETER LIST FOR QUERY WINDOW POSITION ON SCREEN 


QORETNCD 
OOFXNID 

QOSESSID 
QOSCRPRO 
QOWINDN 

QOROWNUM 
QOCOLNUM 


° 
, 


OOoO0O0000 


RETURN CODE 

FUNCTION ID 

SESSION ID 

SCREEN PROFILE NUMBER IN ASCII 
WINDOW SHORT NAME IN ASCII 

ROW NUMBER OF UPPER LEFT CORNER 
COLUMN NUMBER OF UPPER LEFT CORNER 


=e se “ee Se Se Se ONO 


; INITIALIZE PARAMETER LIST FOR QUERY WINDOW POSITION ON SCREEN 


. 
r 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


QORETNCD , OOH 


RETURN CODE MUST = O BEFORE REQUEST 


OOFXNID , OOH ; FUNCTION ID MUST = 0 BEFORE REQUEST 
AL, SESSID ; SESSION ID OBTAINED FROM REQUEST 
QOSESSID,AL ; TO QUERY SESSION ID SERVICE 

AT ; SCREEN PROFILE NUMBER 

QOSCRPRO, AL ; IN PARAMETER LIST 

AL,'P' ; WINDOW SHORT NAME OBTAINED FROM 
QOWINDN , AL ; REQUEST TO QUERY SESSION ID SERVICE 


; INITIALIZE REGISTERS FOR QUERY WINDOW POSITION ON SCREEN 


. 
f 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


AH,09H 
AL, OBH 
BH, 80H 
BL, 20H 
CX, OFFH 
DX, WSCTRL 


ES,DI 


DI,OFFSET QQRETNCD 


RESOLVED VALUE FOR WSCTRL 


IN ES 
OFFSET OF PARAMETER LIST IN DI 


DI, SEG QQRETNCD ; SEGMENT ADDRESS OF PARAMETER LIST 


; SIGNAL WORKSTATION PROGRAM FOR QUERY WINDOW POSITION ON SCREEN SERVICE 


7 


INT 


7AH 
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Query Window Size 


Window Management Service X‘0C’: Query Window Size 


Register Values 


Use this service to obtain the size of a window on the specified screen 
profile. The window’s size is given as the number of rows and columns in 
the window. 


On Request On Completion 

AH = X‘09’ CH = X‘12’ 

AL = X‘0C’ CL = Return code 

BH = X‘80’ 

BL = X‘20’ The contents of registers 
CX = X‘O0FF’ AX, BX, DX, ES, and DI 
DX = Resolved value for WSCTRL are unpredictable. 


ES = Segment address of the parameter list 
DI = Offset address of the parameter list 


Parameter List Format 
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Contents Contents 
Offset Length on Request on Completion 


jot byte 


1 1 byte Must be zero Function ID 
(X‘63’) 


3 1 byte Screen profile Unchanged 
number 

4 1 byte Window short Unchanged 
name 


fe _[tbyte [Reserved [Columns 


Query Window Size 


Parameter Definitions 


Return Codes 


Request Parameters: 


The session ID is the ID of the session currently connected to the work 
station control session. 


The screen profile number is the number (in ASCII) of the screen profile 
containing the specified window. 


The window short name is the 1-character ASCII name for the window 
being queried. Window short names must be alphabetic characters. 


Completion Parameters: 


“Rows” is the number of rows in the window size. 


“Columns” is the number of columns in the window size. 


System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


Window Management Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the window management portion of the workstation program. The 
function ID is in byte 1, and the error number is in byte 0. Window 
management return codes use a function ID of X‘63’. The error codes 
that can be received for this service are: 


Code Meaning 


X‘00’ Successful completion. 

X‘02’ Invalid session ID. 

X‘04’ The session is not connected for window management 
services. 

X‘06’ Invalid screen ID. 

X‘07’ The window is not found on screen. 

X‘0C’ Byte 0 of the parameter list is not zero on request. 

X‘OE’ No windows exist on screen. 


See Appendix H, “Return Codes,” for more information. 
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Query Window Size 


Coding Example 
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° 
i 


; PARAMETER LIST FOR QUERY WINDOW SIZE 


QZRETNCD 
QZFXNID 
QZSESSID 
QZSCREEN 
OZWINDOW 
QZROWS 
QZCOLUMS 


. 
/ 


oOO0O000 0 


at at Sat Sn St St at 


RETURN CODE 

FUNCTION NUMBER 

SESSION ID 

SCREEN PROFILE NUMBER 

WINDOW SHORT NAME 

NUMBER OF ROWS IN WINDOW SIZE 
NUMBER OF COLUMNS IN WINDOW SIZE 


; INITIALIZE PARAMETER LIST FOR QUERY WINDOW SIZE 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


QZRETNCD , OOH 
OZFXNID, 00H 
AL, SESSID 

QZSESSID,AL 
OZSCREEN,'4' 
QZWINDOW,'D' 


Ct i et eT eT | 


RETURN CODE MUST = O BEFORE REQUEST 
FUNCTION ID MUST = O BEFORE REQUEST 
SESSION ID INTO THE 

PARAMETER LIST 

SCREEN NUMBER 4 

WINDOW 'D' SHORT NAME INTO THE LIST 


; INITIALIZE REGISTERS FOR QUERY WINDOW SIZE 


° 
, 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


AH, 09H 

AL, OCH 

BH, 80H 

BL, 20H 

CX, OFFH 

DX, WSCTRL 

DI, SEG QZRETNCD 
ES,DI 

DI,OFFSET QZRETNCD 


e 
f 
. 
t 
, 
. 
r 


RESOLVED VALUE FOR 'WSCTRL  ' 

SEGMENT ADDRESS OF PARAMETER LIST 
IN ES 

OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR QUERY WINDOW SIZE SERVICE 


e 
, 


INT 


7AH 


Query Window Colors 


Window Management Service X‘0D’: Query Window 
Colors 


Use this service to obtain the foreground and background colors of a 
window on the specified screen profile. 


Register Values 


On Request On Completion 

AH = X‘09’ CH = X‘12’ 

AL = X‘0D’ CL = Return code 

BH = X‘80’ 

BL = X‘20’ The contents of registers 
CX = X‘O0FF’ AX, BX, DX, ES, and DI 
DX = Resolved value for WSCTRL are unpredictable. 

ES = Segment address of the parameter list 

DI = Offset address of the parameter list 


Parameter List Format 


Contents Contents 
Offset Length on Request on Completion 


1 byte 


1 1 byte Must be zero Function ID 
(X‘63’) 


3 1 byte Screen profile Unchanged 
number 

4 1 byte Window short Unchanged 
name 


Foreground color 
[6 |ityte | Reserved | Background color 
1 byte Color flag 
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Query Window Colors 


Parameter Definitions 


6-48 


Request Parameters: 


e The session ID is the ID of the session currently connected to the work 
station control session. 


e The screen profile number is the number (in ASCII) of the screen profile 
containing the specified window. 


e The window short name is the 1-character ASCII name for the window 
being queried. Window short names must be alphabetic characters. 


Completion Parameters: 


e The foreground and background color values are as follows: 
Value Color 


Black 
Blue 

Red 

Pink 
Green 
Turquoise 
Yellow 
White 


fel te wt te te ued 


“Don WN FH © 


e The color flag is as follows: 


0 = Normal 
(foreground/background color values apply) 


1 = Base mode 
(base colors apply) 


2 = PC session 


Note: If the color flag value is 1 or 2, the foreground and 
background color values are both 0. 


Return Codes 


Query Window Colors 


e System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


e Window Management Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the window management portion of the workstation program. The 
function ID is in byte 1, and the error number is in byte 0. Window 
management return codes use a function ID of X‘63’. The error codes 
that can be received for this service are: 


Code 


X*‘00’ 
X ‘02’ 
X‘04’ 


X ‘06’ 
X‘07’ 
X‘0C’ 
X‘0E’ 


Meaning 


Successful completion. 

Invalid session ID. 

The session is not connected for window management 
services. 

Invalid screen ID. 

The window is not found on screen. 

Byte 0 of the parameter list is not zero on request. 
No windows exist on screen. 


See Appendix H, “Return Codes,” for more information. 
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Query Window Colors 


Coding Example 
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. 
, 


; PARAMETER LIST FOR QUERY WINDOW COLORS 


QCRETNCD 
OCFXNID 

QCSESSID 
QCSCRPRO 
OCWINDN 

QCFORCOL 
QCBAKCOL 
QCCOLFLG 


° 
7 


OOO00000 


ee et et ee eT | Ts 


RETURN CODE 

FUNCTION ID 

SESSION ID 

SCREEN PROFILE NUMBER IN ASCII 
WINDOW SHORT NAME IN ASCII 
FOREGROUND COLOR 

BACKGROUND COLOR 

COLOR FLAG 


; INITIALIZE PARAMETER LIST FOR QUERY WINDOW COLORS 


e 
, 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


OCRETNCD , OOH 
OCFXNID,OOH 
AL,SESSID 
QCSESSID,AL 
Ale 
QCSCRPRO, AL 
AL,'P! 
QCWINDN, AL 


et St et et eT ee Td 


RETURN CODE MUST = O BEFORE REQUEST 
FUNCTION ID MUST = O BEFORE REQUEST 
SESSION ID OBTAINED FROM REQUEST 

TO QUERY SESSION ID SERVICE 

SCREEN PROFILE NUMBER 1 

IN PARAMETER LIST 

WINDOW SHORT NAME 'P' 

IN PARAMETER LIST 


; INITIALIZE REGISTERS FOR QUERY WINDOW COLORS 


° 
i 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


AH,0O9H 

AL, ODH 

BH, 80H 

BL,20H 

CX, OFFH 

DX, WSCTRL 

DI, SEG QCRETNCD 
ES,DI 

DL,OFFSET QCRETNCD 


t 
. 
t 
. 
f 
. 
‘ 


RESOLVED VALUE FOR WSCTRL 

SEGMENT ADDRESS OF PARAMETER LIST 
IN ES 

OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR QUERY WINDOW COLORS SERVICE 


° 
y 


INT 


7AH 


Query Window Position on Presentation Space 


Window Management Service X‘0E’: Query Window 
Position on Presentation Space 


Register Values 


Use this service to obtain the position of a window on the presentation 
space for the specified screen profile. The window’s position is given by the 
row and column numbers of the upper left corner of the window. 


On Request On Completion 

AH = X‘09’ CH = X‘12’ 

AL = X‘0E’ CL = Return code 

BH = X‘80’ 

BL = X‘20’ The contents of registers 
CX = X‘O0FF’ AX, BX, DX, ES, and DI 
DX = Resolved value for WSCTRL are unpredictable. 

ES = Segment address of the parameter list 

DI = Offset address of the parameter list 


Parameter List Format 


Contents Contents 
Offset Length on Request on Completion | 


1 byte 


1 1 byte Must be zero Function ID 
(X‘63’) 


2 

3 1 byte Screen profile Unchanged 
number 

4 1 byte Window short Unchanged 
name 


fe [atyie [Reseeved [Column 
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Query Window Position on Presentation Space 


- Parameter Definitions 
Request Parameters: 


e The session ID is the ID of the session currently connected to the work 
station control session. 


e The screen profile number is the number (in ASCII) of the screen profile 
containing the specified window. 


e The window short name is the 1-character ASCII name for the window 
being queried. Window short names must be alphabetic characters. 


Completion Parameters: 


e “Row” is the row number of the upper left corner of the window on the 
presentation space. 


e “Column” is the column number of the upper left corner of the window 
on the presentation space. 


Return Codes 
e System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


e Window Management Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the window management portion of the workstation program. The 
function ID is in byte 1, and the error number is in byte 0. Window 
management return codes use a function ID of X‘63’. The error codes 
that can be received for this service are: 


Code Meaning 


X‘00’ Successful completion. 

X‘02’ Invalid session ID. 

X ‘04’ The session is not connected for window management 
services. 

X‘06’ Invalid screen ID. 

X‘07’ The window is not found on screen. 

X‘0C’ Byte 0 of the parameter list is not zero on request. 

X‘0E’ No windows exist on screen. 


See Appendix H, “Return Codes,” for more information. 
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Coding Example 


. 
i 


Query Window Position on Presentation Space 


; PARAMETER LIST FOR QUERY WINDOW POSITION ON PRESENTATION SPACE 


QPRETNCD 
QPFXNID 
QPSESSID 
QOPSCREEN 
QPWINDOW 
QPROW 
QPCOLUMN 


et TY 


me te Ne te 


ST iT at! 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


INT 


oOO0O0000 


QPRETNCD , OOH 
QPFXNID, 00H 
AL,SESSID 

QPSESSID,AL 
QPSCREEN,'3! 
QPWINDOW,'J' 


AH ,O9H 

AL , OEH 

BH , 80H 

BL, 20H 

CX, OF FH 

DX ,WSCTRL 

DI, SEG QPRETNCD 
ES,DI 

DI,OFFSET QPRETNCD 


7AH 


=e we Se Se Me NO NO 


A it BT eT BT 


. 
a 
° 
f 
tA 
tA 


RETURN CODE 

FUNCTION NUMBER 

SESSION ID 

SCREEN PROFILE NUMBER 

WINDOW SHORT NAME 

ROW NUMBER OF UPPER LEFT CORNER 
COLUMN NUMBER OF UPPER LEFT CORNER 


INITIALIZE PARAMETER LIST FOR QUERY WINDOW POSITION ON 
PRESENTATION SPACE 


RETURN CODE MUST 
FUNCTION ID MUST 
SESSION ID INTO THE 
PARAMETER LIST 

SCREEN NUMBER 3 
WINDOW 'J' SHORT NAME 


0 BEFORE REQUEST 
0 BEFORE REQUEST 


INITIALIZE REGISTERS FOR QUERY WINDOW POSITION ON 
PRESENTATION SPACE 


RESOLVED VALUE FOR 'WSCTRL ' 
SEGMENT ADDRESS OF PARAMETER LIST 
IN ES 

OFFSET OF PARAMETER LIST IN DI 


SIGNAL WORKSTATION PROGRAM FOR QUERY WINDOW POSITION ON 
PRESENTATION SPACE SERVICE 
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Query Hidden State 


Window Management Service X‘0F’: Query Hidden State 


Register Values 


Use this service to obtain the “hidden” state of a window on the specified 
screen profile. (The hidden state tells whether the window is hidden or not 
hidden.) 


On Request On Completion 

AH = X‘09’ CH = X‘12’ 

AL = X‘0F’ CL = Return code 

BH = X‘80’ 

BL = X‘20’ The contents of registers 
CX = X‘00FF’ AX, BX, DX, ES, and DI 
DX = Resolved value for WSCTRL are unpredictable. 

ES = Segment address of the parameter list 

DI = Offset address of the parameter list 


Parameter List Format 
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Contents Contents 
Offset Length on Request on Completion 


fo (| 1 byte 


1 1 byte Must be zero Function ID 
(X‘63’) 


3 1 byte Screen profile Unchanged 
number 


4 1 byte Window short Unchanged 


name ; 
1 byte Reserved “Hidden” flag 


Query Hidden State 


Parameter Definitions 


Return Codes 


Request Parameters: 


The session ID is the ID of the session currently connected to the work 
station control session. 


The screen profile number is the number (in ASCII) of the screen profile 
containing the specified window. 


The window short name is the 1-character ASCII name for the window 
being queried. Window short names must be alphabetic characters. 


Completion Parameters: 


The “hidden” flag is as follows: 


~ A value of X‘01’ in the “hidden” flag means that the window is 
hidden. 


— A value of X‘00’ in the “hidden” flag means that the window is not 
hidden. 


System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


Window Management Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the window management portion of the workstation program. The 
function ID is in byte 1, and the error number is in byte 0. Window 
management return codes use a function ID of X‘63’. The error codes 
that can be received for this service are: 


Code Meaning 


X‘00’ Successful completion. 

X ‘02’ Invalid session ID. 

X‘04’ The session is not connected for window management 
services. 

X‘06’ Invalid screen ID. 

X‘07’ The window is not found on screen. 

X‘0C’ Byte 0 of the parameter list is not zero on request. 

X‘0E’ No windows exist on screen. 


See Appendix H, “Return Codes,” for more information. 
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Query Hidden State 


Coding Example 
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e 
, 


; PARAMETER LIST FOR QUERY HIDDEN STATE 


QHRETNCD 
QHFXNID 
QHSESSID 
QHSCRPRO 
QHWINDN 
QHHIDFLG 


eT iT) 


 ~e Ne Ne 


° 
f 


DB 
DB 
DB 
DB 
DB 
DB 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


ooo000 


QHRETNCD , OOH 
QHFXNID, OOH 
AL,SESSID 
QHSESSID,AL 
ALG hi! 
QHSCRPRO , AL 
AL,'P! 
QHWINDN, AL 


AH, 09H 

AL, OFH 

BH, 80H 

BL,20H 

CX, OF FH 

DX ,WSCTRL 

DI, SEG QHRETNCD 
ES,DI 

DI,OFFSET QHRETNCD 


“ese se Ne Ne Ne Ne 


aT SE i i Se nL | 


. 
f 
. 
f 
° 
a 
. 
Ul 


RETURN CODE 

FUNCTION ID 

SESSION ID 

SCREEN PROFILE NUMBER IN ASCII 
WINDOW SHORT NAME IN ASCII 
HIDDEN FLAG 


INITIALIZE PARAMETER LIST FOR QUERY HIDDEN STATE 


RETURN CODE MUST = O BEFORE REQUEST 
FUNCTION ID MUST = 0 BEFORE REQUEST 
SESSION ID OBTAINED FROM REQUEST 

TO QUERY SESSION ID SERVICE 

SCREEN PROFILE NUMBER 

IN PARAMETER LIST 

WINDOW SHORT NAME 

IN PARAMETER LIST 


INITIALIZE REGISTERS FOR QUERY HIDDEN STATE 


RESOLVED VALUE FOR WSCTRL 

SEGMENT ADDRESS OF PARAMETER LIST 
IN ES 

OFFSET OF PARAMETER LIST IN DI 


+ SIGNAL WORKSTATION PROGRAM FOR QUERY HIDDEN STATE SERVICE 


. 
, 


INT 


7AH 


Query Enlarge State 


Window Management Service X‘10’: Query Enlarge State 


Use this service to obtain the “enlarge” state of the display image. (The 
display image can be either enlarged or not enlarged. In an enlarged 
image, the active window is displayed on the entire screen.) 


Register Values 


On Request On Completion 

AH = X‘09’ CH = X‘12’ 

AL = X‘10’ CL = Return code 

BH = X‘80’ 

BL = X‘20’ The contents of registers 
CX = X‘O0FF’ AX, BX, DX, ES, and DI 
DX = Resolved value for WSCTRL are unpredictable. 

ES = Segment address of the parameter list 

DI = Offset address of the parameter list 


Parameter List Format 


| | Contents Contents 
—— Length on Request 0n Completion 


1 byte Must be zero Function ID 
(X‘63’) 


a __[1tyte [Session D____[ Unchanged 


jo | A byte 
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Query Enlarge State 


Parameter Definitions 
Request Parameters: 


e The session ID is the ID of the session currently connected to the work 
station control session. 


Completion Parameters: 
e The “enlarge” flag is as follows: 


— A value of X‘01’ in the “enlarge” flag means that the display image 
is enlarged. 


— A value of X‘00’ in the “enlarge” flag means that the display image 
is not enlarged. 


Return Codes 
e System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


e Window Management Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the window management portion of the workstation program. The 
function ID is in byte 1, and the error number is in byte 0. Window 
management return codes use a function ID of X‘63’. The error codes 
that can be received for this service are: 


Code Meaning 


X‘00’ Successful completion. 

X‘02’ Invalid session ID. 

X‘04’ The session is not connected for window management 
services. 

X‘0C’ Byte 0 of the parameter list is not zero on request. 


See Appendix H, “Return Codes,” for more information. 
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Coding Example 


a 
, 


. 
f 


QERETNCD DB 
QEFXNID DB 
QESESSID DB 
QEENLFLG DB 


° 
‘ 


° 
, 


° 
, 


° 
/ 


° 
t 
° 
a 


° 
! 


oO0O00 


PARAMETER LIST FOR QUERY ENLARGE 


~e se Ne Ne 


Query Enlarge State 


STATE 


RETURN CODE 
FUNCTION NUMBER 
SESSION ID 
ENLARGE FLAG 


INITIALIZE PARAMETER LIST FOR QUERY ENLARGE STATE 


MOV 
MOV 
MOV 
MOV 


QERETNCD , 0OH 
OEFXNID, 00H 


AL,SESSID 


QESESSID,AL 


oe et eT 


RETURN CODE MUST = O BEFORE REQUEST 
FUNCTION ID MUST = 0 BEFORE REQUEST 
SESSION ID INTO THE 

PARAMETER LIST 


INITIALIZE REGISTERS FOR QUERY ENLARGE STATE 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


AH,09H 
AL,10H 
BH, 80H 
BL, 20H 
CX, OF FH 
DX,WSCTRL 


DI, SEG QERETNCD 


ES,DI 


DI,OFFSET QERETNCD 


. 
t 
. 
ta 
. 
‘ 
° 
, 


RESOLVED VALUE FOR 'WSCTRL ' 
SEGMENT ADDRESS OF PARAMETER LIST 
IN ES 

OFFSET OF PARAMETER LIST IN DI 


SIGNAL WORKSTATION PROGRAM FOR QUERY ENLARGE STATE SERVICE 


INT 


7AH 
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Query Screen Background Color 


Window Management Service X‘11’: Query Screen 


Background Color 


Use this service to obtain the background color of the specified screen 


profile. 
Register Values 

On Request 
AH = X‘09’ 
AL = X‘11’ 
BH = X‘80’ 
BL = X‘20’ 
CX = X‘OOFF’ 


DX = Resolved value for WSCTRL 
Segment address of the parameter list 
Offset address of the parameter list 
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Contents Contents 
Offset Length on Request on Completion 


1 byte 


1 1 byte Must be zero Function ID 
(X‘63’) 


i byt Unchanged 
3 1 byte Screen profile 
number 
4 1 byte Reserved Screen 
background color 


On Completion 


CH = X‘12’ 
CL = Return code 


The contents of registers 
AX, BX, DX, ES, and DI 
are unpredictable. 


Query Screen Background Color 


Parameter Definitions 


Return Codes 


Request Parameters: 


The session ID is the ID of the session currently connected to the work 
station control session. 


The screen profile number is the number (in ASCII) of the screen profile 
being queried. 


Completion Parameters: 


The background color values are as follows: 
Value Color 


Black 
Blue 

Red 

Pink 
Green 
Turquoise 
Yellow 
White 


NOP WN re © 


System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


Window Management Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the window management portion of the workstation program. The 
function ID is in byte 1, and the error number is in byte 0. Window 
management return codes use a function ID of X‘63’. The error codes 
that can be received for this service are: 


Code Meaning 


X‘00’ Successful completion. 

X‘02? Invalid session ID. . 

X‘04’ The session is not connected for window management 
services. : 

X‘06’ Invalid screen ID. 

X‘0C’ Byte 0 of the parameter list is not zero on request. 


See Appendix H, “Return Codes,” for more information. 
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Query Screen Background Color 


Coding Example 
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. 
, 


; PARAMETER LIST FOR QUERY SCREEN BACKGROUND COLOR 


QBRETNCD 
QOBFXNID 

QBSESSID 
QOBSCRPRO 
OBBAKCOL 


* 
tA 


DB 
DB 
DB 
DB 
DB 


OO000 


se Oe te Ne Ne 


RETURN CODE 

FUNCTION ID 

SESSION ID 

SCREEN PROFILE NUMBER IN ASCII 
SCREEN BACKGROUND COLOR 


; INITIALIZE PARAMETER LIST FOR QUERY SCREEN BACKGROUND COLOR 


e 
a 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


QBRETNCD , OOH 
QBFXNID,0OOH 
AL,SESSID 
QBSESSID,AL 
Ae el 
QBSCRPRO,AL 


~e Se Ne Me Ne Ne 


RETURN CODE MUST = 0 BEFORE REQUEST 
FUNCTION ID MUST = 0 BEFORE REQUEST 
SESSION ID OBTAINED FROM REQUEST 

TO QUERY SESSION ID SERVICE 

SCREEN PROFILE NUMBER 

IN PARAMETER LIST 


; INITIALIZE REGISTERS FOR QUERY SCREEN BACKGROUND COLOR 


e 
i 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


AH ,09H 

AL,11H 

BH, 80H 

BL, 20H 

CX, OFFH 

DX ,WSCTRL 

DI, SEG QBRETNCD 
ES,DI 

DI,OFFSET QBRETNCD 


° 
, 
e 
, 
° 
7 
° 
, 


RESOLVED VALUE FOR WSCTRL 

SEGMENT ADDRESS OF PARAMETER LIST 
IN ES 

OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR QUERY SCREEN BACKGROUND COLOR SERVICE 


e 
f 


INT 


7AH 


Query Window Names 


Window Management Service X‘12’: Query Window 
Names 


Use this service to obtain the short names of all windows in the specified 
screen profile. 


Register Values 


On Request On Completion 

AH = X‘09’ CH = X‘12’ 

AL = X‘12’ CL = Return code 

BH = X‘80’ 

BL = X‘20’ The contents of registers 
CX = X‘O0FF’ AX, BX, DX, ES, and DI 
DX = Resolved value for WSCTRL are unpredictable. 

ES = Segment address of the parameter list 


Offset address of the parameter list 


3 1 byte Screen profile Unchanged 
number 


byte Window short name # 
Window short name #2 
Window short name #3 
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Query Window Names 


Parameter Definitions 


Return Codes 


Usage Notes 
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Request Parameters: 


The session ID is the ID of the session currently connected to the work 
station control session. 


The screen profile number is the number (in ASCII) of the screen profile 
being queried. 


Completion Parameters: 


The window short name is the 1-character ASCII name for the window 
on the specified screen profile. Window short names are uppercase 
alphabetic characters. 


System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


Window Management Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the window management portion of the workstation program. The 
function ID is in byte 1, and the error number is in byte 0. Window 
management return codes use a function ID of X‘63’. The error codes 
that can be received for this service are: 


Code Meaning 


X ‘00’ Successful completion. 

X‘02’ Invalid session ID. 

X‘04’ The session is not connected for window management 
| services. 

X ‘06’ Invalid screen ID. 

X‘0C’ Byte 0 of the parameter list is not zero on request. 

X‘0R’ No windows exist on the screen. 


See Appendix H, “Return Codes,” for more information. 


The windows are listed in the parameter list in the order they appear on 
the screen. , 


The parameter list is filled with blanks (X‘20’) after all window names 
have been given. 


Coding Example 


. 
’ 


Query Window Names 


; PARAMETER LIST FOR QUERY WINDOW NAMES 


QWRETNCD 
QWFXNID 

QWSESSID 
QWSCREEN 
QWWNDLST 


° 
/ 


DB 
DB 
DB 
DB 
DB 


0 
O 
0 
0 
2 


O DUP(0O) 


RETURN CODE 

FUNCTION NUMBER 

SESSION ID 

SCREEN PROFILE NUMBER 

LIST OF WINDOW SHORT NAMES 


“=e “Se Se Se Ne 


; INITIALIZE PARAMETER LIST FOR QUERY WINDOW NAMES 


° 
’ 


° 
f 


MOV 
MOV 
MOV 
MOV 
MOV 


QWRETNCD , OOH 
QWFXNID, OOH 


AL,SESSID 


QWSESSID, AL 
QWSCREEN,'1' 


RETURN CODE MUST = O BEFORE REQUEST 
FUNCTION ID MUST = O BEFORE REQUEST 
SESSION ID INTO THE 

PARAMETER LIST 

SCREEN NUMBER 1 


bt at eT ey | 


; INITIALIZE REGISTERS FOR QUERY WINDOW NAMES 


. 
f 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


AH,0O9H 
AL,12H 
BH, 80H 
BL,20H 
CX, OF FH 
DX ,WSCTRL 


ES,DI 


DI,OFFSET QWRETNCD 


RESOLVED VALUE FOR 'WSCTRL ' 


IN ES 
OFFSET OF PARAMETER LIST IN DI 


DI, SEG QWRETNCD ; SEGMENT ADDRESS OF PARAMETER LIST 


; SIGNAL WORKSTATION PROGRAM FOR QUERY WINDOW NAMES SERVICE 


. 
i 


INT 


7AH 
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Clear Screen 


Window Management Service X‘13’: Clear Screen 


Use this service to delete all windows from the specified screen profile. 
Windows cannot be deleted from screen profile 0. 


Register Values 


On Request On Completion 

AH = X‘09’ CH = X‘12’ 

AL = X‘13’ CL = Return code 

BH = X‘80’ 

BL = X‘20’ The contents of registers 
CX = X‘00FF’ AX, BX, DX, ES, and DI 
DX = Resolved value for WSCTRL are unpredictable. 

ES = Segment address of the parameter list 


DI Offset address of the parameter list 


Parameter List Format 


Contents Contents 
Offset Length on Request on Completion 


1 byte 


1 1 byte Must be zero Function ID 
(X‘63’) 


3 1 byte Screen profile Unchanged 
number 


Parameter Definitions 


Request Parameters: 


e The session ID is the ID of the session currently connected to the work 
station control session. 


e The screen profile number is the number (in ASCID) of the screen profile 
being cleared. 
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Clear Screen 


Return Codes 
e System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


e Window Management Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the window management portion of the workstation program. The 
function ID is in byte 1, and the error number is in byte 0. Window 
management return codes use a function ID of X‘63’. The error codes 
that can be received for this service are: 


Code Meaning 


X‘00’ Successful completion. 

X‘02’ Invalid session ID. 

X‘04’ The session is not connected for window management 
services. 

X ‘06’ Invalid screen ID. 

X‘0C’ Byte 0 of the parameter list is not zero on request. 


See Appendix H, “Return Codes,” for more information. 


Usage Notes 


e Windows cannot be deleted from screen profile 0. 
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Clear Screen 


Coding Example 
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. 
t 
. 
’ 


CLRETNCD DB 
CLFXNID DB 
CLSESSID DB 
CLSCRPRO DB 


‘ 


f 


. 
‘ 


oOoo0°0o 


PARAMETER LIST FOR CLEAR SCREEN 


se Ne Ne NO 


RETURN CODE 
FUNCTION ID 
SESSION ID 
SCREEN PROFILE NUMBER IN ASCII 


INITIALIZE PARAMETER LIST FOR CLEAR SCREEN 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


CLRETNCD , OOH 
CLFXNID, 00H 
AL,SESSID 
CLSESSID,AL 
AL,'1' 
CLSCRPRO,AL 


et ey eT i | 


RETURN CODE MUST QO BEFORE REQUEST 
FUNCTION ID MUST 0 BEFORE REQUEST 
SESSION ID OBTAINED FROM REQUEST 

TO QUERY SESSION ID SERVICE 

SCREEN PROFILE NUMBER 

IN PARAMETER LIST 


i 


INITIALIZE REGISTERS FOR CLEAR SCREEN 


MOV 
MOV 
MOV 
“MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


AH, 09H 

AL, 13H 

BH , 80H 

BL, 20H 

CX, OF FH 

DX ,WSCTRL 

DI, SEG CLRETNCD 
ES ,DI 

DI,OFFSET CLRETNCD 


° 
tf 
. 
a 
. 
7 
° 
f 


RESOLVED VALUE FOR WSCTRL 

SEGMENT ADDRESS OF PARAMETER LIST 
IN ES 

OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR CLEAR SCREEN SERVICE 


. 
' 


INT 


7AH 


Select Active Window 


Window Management Service X‘14’: Select Active 


Window 


Register Values 


Use this service to select a window on the specified screen profile to become 
the active window. 


On Request On Completion 

AH = X‘09’ CH = X‘12’ 

AL = X‘14’ CL = Return code 

BH = X‘80’ 

BL = X‘20’ The contents of registers 
CX = X‘0O0FF’ AX, BX, DX, ES, and DI 
DX = Resolved value for WSCTRL are unpredictable. 


ES = Segment address of the parameter list 
DI = Offset address of the parameter list 


Parameter List Format 


Contents Contents 
Offset Length on Request on Completion 


ae 


1 1 byte Must be zero Function ID 
(X‘63’) 


1 byte Unchanged 
3 1 byte Screen profile Unchanged 
number 
4 1 byte Window short Unchanged 
name 
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Select Active Window 


Parameter Definitions 


Return Codes 
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Request Parameters: 


The session ID is the ID of the session currently connected to the work 
station control session. 


The screen profile number is the number (in ASCII) of the screen profile 
containing the specified window. 


The window short name is the 1-character ASCII name for the window 
being made active. Window short names must be alphabetic characters. 


System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


Window Management Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the window management portion of the workstation program. The 
function ID is in byte 1, and the error number is in byte 0. Window 
management return codes use a function ID of X‘63’. The error codes 
that can be received for this service are: 


Code Meaning 


X‘00’ Successful completion. 

X‘02’ Invalid session ID. 

X‘04’ The session is not connected for window management 
services. 

X‘06’ Invalid screen ID. 

X‘07’ The window is not found on screen. 

X‘0C’ Byte 0 of the parameter list is not zero on request. 

X‘0E’ No windows exist on screen. 


See Appendix H, “Return Codes,” for more information. 


Coding Example 


. 
, 


Select Active Window 


; PARAMETER LIST FOR SELECT ACTIVE WINDOW 


ACRETNCD 
ACFXNID 

ACSESSID 
ACSCREEN 
ACWINDOW 


. 
’ 


DB 
DB 
DB 
DB 
DB 


O0O000 


RETURN CODE 

FUNCTION NUMBER 
SESSION ID 

SCREEN PROFILE NUMBER 
WINDOW SHORT NAME 


me se Se Ne Ne 


; INITIALIZE PARAMETER LIST FOR SELECT ACTIVE WINDOW 


e 
i 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


ACRETNCD , OOH 
ACFXNID, 00H 


AL, SESSID 


ACSESSID,AL 
ACSCREEN,'1! 
ACWINDOW,'C! 


RETURN CODE MUST 
FUNCTION ID MUST 
SESSION ID INTO THE 
PARAMETER LIST 

SCREEN NUMBER 1 
WINDOW 'C' SHORT NAME 


O BEFORE REQUEST 
O BEFORE REQUEST 


Ce er eT eT eT 


; INITIALIZE REGISTERS FOR SELECT ACTIVE WINDOW 


e 
f 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


AH, 09H 
AL, 14H 
BH, 80H 
BL,20H 
CX, OF FH 
DX,WSCTRL 


ES,DI 


DI,OFFSET ACRETNCD 


RESOLVED VALUE FOR 'WSCTRL ' 


IN ES 
OFFSET OF PARAMETER LIST IN DI 


DI, SEG ACRETNCD ; SEGMENT ADDRESS OF PARAMETER LIST 


; SIGNAL WORKSTATION PROGRAM FOR SELECT ACTIVE WINDOW SERVICE 


. 
, 


INT 


7AH 
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Redraw Screen 


Window Management Service X‘15’: Redraw Screen 


Use this service to redraw the specified screen profile if it is the active 


screen. 
Register Values 

On Request On Completion 

AH = X‘09’ CH = X‘12’ 

AL = X‘15’ CL = Return code 

BH = X‘80’ 

BL = X‘20’ The contents of registers 

CX = X‘OOFF’ AX, BX, DX, ES, and DI 

DX = Resolved value for WSCTRL are unpredictable. 

ES = Segment address of the parameter list 


Offset address of the parameter list 


Parameter List Format 


Contents Contents 
Offset Length on Request on Completion 


jo A byte 


1 1 byte Must be zero Function ID 
(X‘63’) 


Unchanged 


3 1 byte Screen profile Unchanged 
number 


Parameter Definitions 


Request Parameters: 


e The session ID is the ID of the session currently connected to the work 
station control session. 


e The screen profile number is the number (in ASCI)) of the screen profile 
being redrawn. 
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Redraw Screen 


Return Codes 
e System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


e Window Management Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the window management portion of the workstation program. The 
function ID is in byte 1, and the error number is in byte 0. Window 
management return codes use a function ID of X‘63’. The error codes 
that can be received for this service are: 


Code Meaning 


X‘00’ Successful completion. 

X‘02’ Invalid session ID. 

X‘04’ The session is not connected for window management 
services. 

X‘06’ Invalid screen ID. 

X‘0C’ Byte 0 of the parameter list is not zero on request. 

X‘0D’ This screen is not the active screen. 


See Appendix H, “Return Codes,” for more information. 


Usage Notes 
e This service is necessary if the position or size of any window on the 
screen has been changed, or if a window has been enlarged, so that the 


change becomes visible. 


e The Disconnect from Work Station Control service also redraws the 
screen. 
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Redraw Screen 


Coding Example 
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. 
’ 


. 
‘ 


PARAMETER LIST FOR REDRAW SCREEN 


RSRETNCD DB 
RSFXNID DB 
RSSESSID DB 
RSSCRPRO DB 


° 
f 


. 
’ 


“=e te Ne 


. 
, 
° 
/ 


° 
f 


oOoO00 


es Se te Ne 


RETURN CODE 
FUNCTION ID 
SESSION ID 
SCREEN PROFILE NUMBER IN ASCII 


INITIALIZE PARAMETER LIST FOR REDRAW SCREEN 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


RSRETNCD , OOH 
RSFXNID, OOH 
AL,SESSID 
RSSESSID,AL 
AL,'1!' 
RSSCRPRO,AL 


=e “ee Se Ne UNO ONO 


RETURN CODE MUST QO BEFORE REQUEST 
FUNCTION ID MUST QO BEFORE REQUEST 
SESSION ID OBTAINED FROM REQUEST 

TO QUERY SESSION ID 

SCREEN PROFILE NUMBER 

IN PARAMETER LIST 


INITIALIZE REGISTERS FOR REDRAW SCREEN 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


AH, 09H 

AL, 15H 

BH, 80H 

BL, 20H 

CX, OFFH 

DX ,WSCTRL 

DI, SEG RSRETNCD 
ES ,DI 

DI,OFFSET RSRETNCD 


. 
, 
° 
’ 
° 
ta 
e 
a 


RESOLVED VALUE FOR WSCTRL 

SEGMENT ADDRESS OF PARAMETER LIST 
IN ES 

OFFSET OF PARAMETER LIST IN DI 


SIGNAL WORKSTATION PROGRAM FOR REDRAW SCREEN SERVICE 


INT 


7AH 


Redraw Window 


Window Management Service X‘16’: Redraw Window 


Register Values 


Use this service to redraw a window on the specified screen profile if it is 
the active screen. 


On Request On Completion 

AH = X‘09’ CH = X‘12’ 

AL = X‘16’ CL = Return code 

BH = X‘80’ 

BL = X‘20’ The contents of registers 
CX = X‘O0FF’ AX, BX, DX, ES, and DI 
DX = Resolved value for WSCTRL are unpredictable. 

ES = Segment address of the parameter list 


DI = Offset address of the parameter list 


Parameter List Format 


Contents Contents 
aaa Length on Request on ae 


fa! byte Must be zero Function Hsu code 
(X‘63’) 


3 1 byte Screen profile Unchanged 
number 

4 1 byte Window short Unchanged 
name 


Parameter Definitions 


Request Parameters: 


e The session ID is the ID of the session currently connected to the work 
station control session. 


e The screen profile number is the number (in ASCID of the screen profile 
containing the specified window. 


e The window short name is the 1-character ASCII name for the window 
being redrawn. Window short names must be alphabetic characters. 
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Redraw Window 


Return Codes 
e System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


e Window Management Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the window management portion of the workstation program. The 
function ID is in byte 1, and the error number is in byte 0. Window 
management return codes use a function ID of X‘63’. The error codes 
that can be received for this service are: 


Code Meaning 


X‘00’ Successful completion. 

X‘02’ Invalid session ID. 

X‘04’ The session is not connected for window management 
services. 

X‘06’ Invalid screen ID. 

X‘07’ The window is not found on screen. 

X‘0C’ Byte 0 of the parameter list is not zero on request. 

X‘0D’ Requested screen not active. 

X‘0E’ No windows exist on screen. 


See Appendix H, “Return Codes,” for more information. 


Usage Notes 


e This service is necessary to make the change visible on the screen when 
the contents of a window or its colors have changed, but the position or 
size of the window has not changed. The Redraw Screen service and 
the Disconnect from Work Station Control service have the same 
function, except that they redraw the entire screen. 
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Redraw Window 


Coding Example 


PARAMETER LIST FOR REDRAW WINDOW 


eo se Ne 


RETURN CODE 

FUNCTION NUMBER 
SESSION ID 

SCREEN PROFILE NUMBER 
WINDOW SHORT NAME 


RWRETNCD DB 
RWFXNID DB 
RWSESSID DB 
RWSCREEN DB 
RWWINDOW DB 


O0O000 


. 


INITIALIZE PARAMETER LIST FOR REDRAW WINDOW 


se Ne Ne 


MOV RWRETNCD,0OOH 
MOV RWFXNID,OOH 
MOV AL,SESSID 

MOV RWSESSID,AL 
MOV RWSCREEN,'7' 
MOV RWWINDOW,'E' 


RETURN CODE MUST = 0 BEFORE REQUEST 
FUNCTION ID MUST = 0 BEFORE REQUEST 
SESSION ID INTO THE 

PARAMETER LIST 

SCREEN NUMBER 7 

WINDOW 'E' SHORT NAME 


~e we Ne Ne Ne NO 


; INITIALIZE REGISTERS FOR REDRAW WINDOW 


MOV AH,O9H 

MOV AL,16H 

MOV BH,80H 

MOV BL,20H 

MOV CX,OFFH 

MOV DX,WSCTRL ; RESOLVED VALUE FOR 'WSCTRL ' 

MOV DI, SEG RWRETNCD  ; SEGMENT ADDRESS OF PARAMETER LIST 
MOV ES,DI ; IN ES 

MOV DI,OFFSET RWRETNCD ; OFFSET OF PARAMETER LIST IN DI 


SIGNAL WORKSTATION PROGRAM FOR REDRAW WINDOW SERVICE 


=e Ne Ne 


INT 7AH 


Chapter 6. Coding Window Management Service Requests 6-77 


Delete Window 


Window Management Service X‘17’: Delete Window 


Use this service to delete a window from the specified screen profile. 
Windows cannot be deleted from screen profile 0. 


Register Values 


On Request On Completion 

AH = X‘09’ CH = X‘12’ 

AL = X‘17’ CL = Return code 

BH = X‘80’ 

BL = X‘20’ The contents of registers 
CX = X‘O0FF’ AX, BX, DX, ES, and DI 
DX = Resolved value for WSCTRL are unpredictable. 

ES = Segment address of the parameter list 


DI Offset address of the parameter list 


Parameter List Format 


Contents Contents 
Offset Length on Request on Completion 


1 byte 


1 1 byte Must be zero Function ID 
(X‘63’) 


3 1 byte Screen profile Unchanged 
number 

4 1 byte Window short Unchanged 
name 


Parameter Definitions 


Request Parameters: 


e The session ID is the ID of the session currently connected to the work 
station control session. 


e The screen profile number is the number (in ASCII) of the screen profile 
containing the specified window. . 


e The window short name is the 1-character ASCII name for the window 
being deleted. Window short names must be alphabetic characters. 
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Delete Window 


Return Codes 
e System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


e Window Management Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the window management portion of the workstation program. The 
function ID is in byte 1, and the error number is in byte 0. Window 
management return codes use a function ID of X‘63’. The error codes 
that can be received for this service are: 


Code Meaning 


X‘00’ Successful completion. 

X ‘02’ Invalid session ID. 

X ‘04’ The session is not connected for window management 
services. 

X ‘06’ Invalid screen ID. 

X‘07’ The window is not found on screen. 

X‘0C’ Byte 0 of the parameter list is not zero on request. 

X ‘OE’ No windows exist on screen. 


See Appendix H, “Return Codes,” for more information. 


Usage Notes 
e Windows cannot be deleted from screen profile 0. 
e If all the remaining windows on the specified screen profile are hidden, 


the next window on the chain will be unhidden and made the active 
window on the screen. 


Chapter 6. Coding Window Management Service Requests 6-79 


Query Active Window 


Coding Example 


° 
’ 


; PARAMETER LIST FOR DELETE WINDOW 


DDRETNCD DB 
DDFXNID DB 
DDSESSID DB 
DDSCRPRO DB 
DDWINDN DB 


RETURN CODE 

FUNCTION ID 

SESSION ID 

SCREEN PROFILE NUMBER IN ASCII 
WINDOW SHORT NAME IN ASCII 


oOO000 


me Ne Ne Ne Ne 


. 
° 


; INITIALIZE PARAMETER LIST FOR DELETE WINDOW 


MOV DDRETNCD,OOH 
MOV DDFXNID,OOH 
MOV AL,SESSID 
MOV  DDSESSID,AL 
MOV AL,'1! 

MOV DDSCRPRO,AL 
MOV AL,'P! 

MOV DDWINDN,AL 


RETURN CODE MUST = O BEFORE REQUEST 
FUNCTION ID MUST = O BEFORE REQUEST 
SESSION ID OBTAINED FROM REQUEST 

TO QUERY SESSION ID SERVICE 

SCREEN PROFILE NUMBER 

IN PARAMETER LIST 

WINDOW SHORT NAME 

IN PARAMETER LIST 


ue “ee se Me Ne te ONO ONO 


; INITIALIZE REGISTERS FOR DELETE WINDOW 


MOV AH,O9H 
MOV AL,17H 
MOV BH,80H 
MOV BL,20H 
MOV CX,OFFH 
MOV DX,WSCTRL ; RESOLVED VALUE FOR WSCTRL 
MOV DI, SEG DDRETNCD  ; SEGMENT ADDRESS OF PARAMETER LIST 
MOV ES,DI ; IN ES 
MOV DI,OFFSET DDRETNCD ; OFFSET OF PARAMETER LIST IN DI 
; SIGNAL WORKSTATION PROGRAM FOR DELETE WINDOW SERVICE 


INT 7AH 
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Query Active Window 


Window Management Service X‘18’: Query Active 


Window 


Register Values 


Use this service to obtain the short name of the active window in the 
specified screen profile. 


On Request On Completion 

AH = X‘09’ CH = X‘12’ 

AL = X‘18’ CL = Return code 

BH = X‘80’ 

BL = X‘20’ The contents of registers 
CX = X‘O0FF’ AX, BX, DX, ES, and DI 
DX = Resolved value for WSCTRL are unpredictable. 

ES = Segment address of the parameter list 


DI Offset address of the parameter list 


Parameter List Format 


Contents Contents 
Offset Length on Request on Completion 


fo ‘da byte 


1 1 byte Must be zero Function ID 
(X‘63’) 
2 


fz [atyte [Session 1D | Unchanged 


3 1 byte Screen profile Unchanged 
number 
4 1 byte Reserved Window short 
name 
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Query Active Window 


Parameter Definitions 
Request Parameters: 


e The session ID is the ID of the session currently connected to the work 
station control session. 


e The screen profile number is the number (in ASCII) of the screen profile 
being queried. 


Completion Parameters: 


e The window short name is the 1-character ASCII name for the active 
window. Window short names are uppercase alphabetic characters. 


Return Codes 
e System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


e Window Management Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the window management portion of the workstation program. The 
function ID is in byte 1, and the error number is in byte 0. Window 
management return codes use a function ID of X‘63’. The error codes 
that can be received for this service are: 


Code Meaning 


X‘00’ Successful completion. 

X‘02’ Invalid session ID. 

X‘04’ The session is not connected for window management 
services. 

X‘06’ Invalid screen ID. 

X‘0C’ Byte 0 of the parameter list is not zero on request. 

X‘0E’ No windows exist on the screen. 


See Appendix H, “Return Codes,” for more information. 
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Coding Example 


Query Active Window 


; PARAMETER LIST FOR QUERY ACTIVE WINDOW 


QNRETNCD 
QNFXNID 

QONSESSID 
ONSCREEN 
QNWINDOW 


° 
ci 


oO0O000 


RETURN CODE 

FUNCTION NUMBER 

SESSION ID 

SCREEN PROFILE NUMBER 
ACTIVE WINDOW SHORT NAME 


“ee “ee Me Ne Ne 


; INITIALIZE PARAMETER LIST FOR QUERY ACTIVE WINDOW 


MOV 
MOV 
MOV 
MOV 
MOV 


ONRETNCD , OOH 
ONFXNID,OOH 


AL, SESSID 


QONSESSID,AL 
ONSCREEN,'0' 


RETURN CODE MUST = O BEFORE REQUEST 
FUNCTION ID MUST = 0 BEFORE REQUEST 
SESSION ID INTO THE 

PARAMETER LIST 

SCREEN NUMBER O 


~e “se Ne Ne Ne 


7 INITIALIZE REGISTERS FOR QUERY ACTIVE WINDOW 


° 
f 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


AH, 09H 
AL, 18H 
BH, 80H 
BL, 20H 
CX, OFFH 
DX ,WSCTRL 


ES,DI 


DI,OFFSET QNRETNCD 


RESOLVED VALUE FOR 'WSCTRL ' 


IN ES 
OFFSET OF PARAMETER LIST IN DI 


DI, SEG QNRETNCD ; SEGMENT ADDRESS OF PARAMETER LIST 


; SIGNAL WORKSTATION PROGRAM FOR QUERY ACTIVE WINDOW SERVICE 


. 
v 


INT 


7AH 
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Query Active Screen 


Window Management Service X‘19’: Query Active Screen 


Use this service to obtain the number of the active screen profile. 


Register Values 


On Request On Completion 

AH = X‘09’ CH = X‘12’ 

AL = X‘19’ CL = Return code 

BH = X‘80’ 

BL = X‘20’ The contents of registers 
CX = X‘O0FF’ AX, BX, DX, ES, and DI 
DX = Resolved value for WSCTRL are unpredictable. 

ES = Segment address of the parameter list 

DI = Offset address of the parameter list 


Contents Contents 
Offset Length on Request on Completion 


1 byte Must be zero 


1 byte Must be zero Function ID 
(X‘63’) 


Session ID 


Reserved Screen profile 
number 


Parameter Definitions 
Request Parameters: 


e The session ID is the ID of the session currently connected to the work 
station control session. 


Completion Parameters: 


e The screen profile number is the number (in ASCII) of the active screen 
profile. 
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Return Codes 
e System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


e Window Management Services Return Codes: 
Bytes 0 and 1 of the parameter list contain a return code generated by 
the window management portion of the workstation program. The 
function ID is in byte 1, and the error number is in byte 0. Window 
management return codes use a function ID of X‘63’. The error codes 
that can be received for this service are: 


Code Meaning 


X‘00° Successful completion. 


X‘02’ Invalid session ID. . 

X‘04’ The session is not connected for window management 
services. 

X‘0C’ Byte 0 of the parameter list is not zero on request. 


See Appendix H, “Return Codes,” for more information. 
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Query Active Screen 


Coding Example 
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o =e Ne 


QARETNCD DB 0 
QAFXNID DB 0 
QASESSID DB 0 
QASCRPRO DB 0 


=e Se Ne 


MOV 
MOV 
MOV 
MOV 


QARETNCD , OOH 
QAFXNID, 00H 
AL ,SESSID 
QASESSID,AL 


. 
, 
e 
f 
° 
a 
° 
‘ 


“se we Ne Ne 


PARAMETER LIST FOR QUERY ACTIVE SCREEN 


RETURN CODE 

FUNCTION ID 

SESSION ID 

SCREEN PROFILE NUMBER IN ASCII 


INITIALIZE PARAMETER LIST FOR QUERY ACTIVE SCREEN 


RETURN CODE MUST = 0 BEFORE REQUEST 
FUNCTION ID MUST = O BEFORE REQUEST 
SESSION ID OBTAINED FROM REQUEST 

TO QUERY SESSION ID 


; INITIALIZE REGISTERS FOR QUERY ACTIVE SCREEN 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


swe oe Ne 


INT 


AH , 09H 

AL, 19H 

BH , 80H 

BL, 20H 

CX, OFFH 

DX,WSCTRL 

DI, SEG QARETNCD 
ES,DI 

DI,OFFSET QARETNCD 


7AH 


° 
, 
. 
a 
e 
f 
f 


RESOLVED VALUE FOR WSCTRL 

SEGMENT ADDRESS OF PARAMETER LIST 
IN ES 

OFFSET OF PARAMETER LIST IN DI 


SIGNAL WORKSTATION PROGRAM FOR QUERY ACTIVE SCREEN SERVICE 


Query Window Attributes 


Window Management Service X‘1A’: Query Window 


Attributes 


Register Values 


Use this service to obtain the following information about a window on the 
specified screen profile: 


On 


The number of rows in the window 
The number of columns in the window 
The row number of the upper left corner of the window on the screen 


The column number of the upper left corner of the window on the 
screen 


Window colors 
Border colors 
Control flags 


The row number of the upper left corner of the window on the 
presentation space 


The column number of the upper left corner of the window on the 
presentation space. 


Segment address of the parameter list 
Offset address of the parameter list 


Request On Completion 
= X‘09’ CH = X‘12’ 
= X‘1A’ CL = Return code 
= X‘80’ 
= X‘20’ The contents of registers 
= X‘O0FF’ AX, BX, DX, ES, and DI 
= Resolved value for WSCTRL are unpredictable. 
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Query Window Attributes 


Parameter List Format 


Contents Contents 
Offset Length on Request on Completion 


= 


1 byte Must be zero Function ID 
(X‘63’) 


1 byte Screen profile Unchanged 
number 

1 byte Window short Unchanged 
name 


| a byte 


a__[ibyte | Reserved | Column on PS 


1 
3 
4 
5 
7 
10 
11 
12 
13 


Parameter Definitions 
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Request Parameters: 


e The session ID is the ID of the session currently connected to the work 
station control session. 


e The screen profile number is the number (in ASCII) of the screen profile 
containing the specified window. 


e The window short name is the 1-character ASCII name for the window 
being queried. Window short names must be alphabetic characters. 


Completion Parameters: 
e “Rows” is the hexadecimal number of rows in the window. 
e “Columns” is the hexadecimal number of columns in the window. 


e “Row on screen” is the row position of the upper left corner of the 
window on the screen. 


e “Column on screen” is the column position of the upper left corner of 
the window on the screen. 


Query Window Attributes 


The window colors are specified as follows: 


2 through 4 5 through 7 
Foreground color Background color 


The foreground and background color values are as follows: 
Value Color 


Black 
Blue 

Red 

Pink 
Green 
Turquoise 
Yellow 
White 


Hou wd we ted 


NOP WN © 


The border colors will always be the same as the window colors (except 
where the window foreground and background colors are the same; in 
that case, the border colors will be white on black). 


The bits in the control flag are as follows: 


fo jtand2 [3 [4ands [6 [7 


Hidden | Reserved | Enlarge | Reserved | Base Window 
_|colors | colors 


— Bit 0 set to 0 means that the window is not hidden. 
If bit 0 is set to 1 and: 


1. Bit 3 is set to 0, the window is hidden. 


2. Bit 3 is set to 1, the window is not hidden (but will not be 
displayed on the screen, because the display is enlarged). 


— Bit 6 set to 0 means that the session is not displayed in the base 
colors. 
Bit 6 set to 1 means that the session is displayed in the base 
colors. 


— Bit 7 set to 0 means that the session is not displayed in the 
foreground and background colors. 
Bit 7 set to 1 means that the session is displayed in the 
foreground and background colors. 


Note: Bits 6 and 7 cannot both be set to 1. 
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Return Codes 
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“Row on PS” is the row position of the upper left corner of the window 
on the presentation space. 


“Column on PS” is the column position of the upper left corner of the 
window on the presentation space. 


System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


Window Management Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the window management portion of the workstation program. The 
function ID is in byte 1, and the error number is in byte 0. Window 
management return codes use a function ID of X‘63’. The error codes 
that can be received for this service are: 


Code Meaning 


X‘00’ Successful completion. 

X‘02’ Invalid session ID. 

X‘04’ The session is not connected for window management 
services. 

X ‘06’ Invalid screen ID. 

X‘07’ The window is not found on screen. 

X‘0C’ Byte 0 of the parameter list is not zero on request. 

X‘0E’ No windows exist on screen. 


See Appendix H, “Return Codes,” for more information. 


° 
f 


Coding Example 


Query Window Attributes 


; PARAMETER LIST FOR QUERY WINDOW ATTRIBUTES 


OF THE WINDOW ON THE 


QTRETNCD DB 0O ; RETURN CODE 
QTFXNID DB O ; FUNCTION NUMBER 
QOTSESSID DB 0 ; SESSION ID 
QTSCREEN DB 0 ; SCREEN PROFILE NUMBER 
QTWINDOW DB 0 ; WINDOW SHORT NAME 
QOTNUMROW DB 0 ; NUMBER OF ROWS IN THE WINDOW 
QTNUMCOL DB 0 ; NUMBER OF COLUMNS IN THE WINDOW 
QTLCRWSC DB O ; ROW NUMBER OF UPPER LEFT CORNER OF 
: THE WINDOW ON THE SCREEN 
QTLCCLSC DB 0 ; COLUMN NUMBER OF UPPER LEFT CORNER 
; OF THE WINDOW ON THE SCREEN 
QTWCOLOR DB O ; WINDOW COLOR ATTRIBUTES 
QTBCOLOR DB 0O ; BORDER COLOR ATTRIBUTES 
QTCTLFLG DB 0 ; CONTROL FLAGS 
OTLCRWPS DB O ; ROW NUMBER OF UPPER LEFT CORNER 
; OF THE WINDOW ON THE 
; PRESENTATION SPACE 
QTLCCLPS DB 0O ; COLUMN NUMBER OF UPPER LEFT CORNER 


. 
f 


PRESENTATION SPACE 


; INITIALIZE PARAMETER LIST FOR QUERY WINDOW ATTRIBUTES 


RETURN CODE MUST 
FUNCTION ID MUST 
SESSION ID INTO THE 
PARAMETER LIST 

SCREEN NUMBER O 
WINDOW 'M' SHORT NAME 


MOV QTRETNCD,OOH 
MOV QTFXNID,OOH 
MOV AL,SESSID 
MOV QTSESSID,AL 
MOV OQTSCREEN,'0' 
MOV QTWINDOW,'M' 


QO BEFORE REQUEST 
QO BEFORE REQUEST 


Wood 


we Ne Me Ne Me te 


. 
, 


; INITIALIZE REGISTERS FOR QUERY WINDOW ATTRIBUTES 


MOV AH,O9H 
MOV AL,1AH 
MOV BH,80H 
MOV BL,20H 
MOV CX,OFFH 
MOV DX,WSCTRL ; RESOLVED VALUE FOR 'WSCTRL ' 
MOV DI, SEG QTRETNCD ; SEGMENT ADDRESS OF PARAMETER LIST 
MOV ES,DI ; IN ES | 
MOV DI,OFFSET QTRETNCD ; OFFSET OF PARAMETER LIST IN DI 
; SIGNAL WORKSTATION PROGRAM FOR QUERY WINDOW ATTRIBUTES SERVICE 


INT 7AH 
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Window Management Service X‘1B’: Cpanee Window 
Attributes 


Use this service to change the following information about a window on the 
specified screen profile: 


e The number of rows in the window 
e The number of columns in the window 
e The row number of the upper left corner of the window on the screen 


e The column number of the upper left corner of the window on the 
screen 


e Window colors 
e Border colors 
e Control flags 


e The row number of the upper left corner of the window on the 
presentation space 


e The column number of the upper left corner of the window on the 
presentation space. 


Register Values 


On Request On Completion 

AH = X‘09’ CH = X‘12’ | 

AL = X‘1B’ CL = Return code 

BH = X‘80’ 

BL = X‘20’ The contents of registers 
CX = X‘O0OFF’ AX, BX, DX, ES, and DI 
DX = Resolved value for WSCTRL are unpredictable. 

ES = Segment address of the parameter list 


DI = Offset address of the parameter list 
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Change Window Attributes 


Parameter List Format 


Contents Contents 
Offset Length on Request on Completion 


1 byte 


1 1 byte Must be zero Function ID 
(X‘63’) 


3 1 byte Screen profile Unchanged 
number 

4 1 byte Window short Unchanged 
name 


[6 | 1byte [Columns | Unchanged * 
fs [1tyte | Column on screen | Unchanged * | 
[9] byte | Window colors | Unchanged 


* These values may be changed by the workstation program. See “Usage Notes” for 
_ more information. 


Parameter Definitions 
Request Parameters: 


e The session ID is the ID of the session currently connected to the work 
station control session. 


e The screen profile number is the number (in ASCII) of the screen profile 
containing the specified window. 


e The window short name is the 1-character ASCII name for the window 
being changed. Window short names must be alphabetic characters. 


e “Rows” is the number of rows in the window. 
e “Columns” is the number of columns in the window. 


e “Row on screen” is the row position of the upper left corner of the 
window on the screen. 


e “Column on screen” is the column position of the upper left corner of 
the window on the screen. 
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The window colors are specified as follows: 


2 through 4 5 through 7 
Foreground color Background color 


The foreground and background color values are as follows: 
Value Color 


Black 
Blue 

Red 

Pink 
Green 
Turquoise 
Yellow 
White 


fol t te ot th aod 


NAD OP GDN © 


The border colors will always be the same as the window colors (except 
where the window foreground and background colors are the same; in 
that case, the border colors will be white on black). 


Note: If the window and border color attributes do not match, the border 
color will be changed to match the window colors. 


The bits in the control flag are as follows: 


f4and5 [6 7 


Enlarge Reserved | Base Window 
colors | colors 


— Bit 0 set to 0 means that the window is not hidden. 
If bit 0 is set to 1 and: 


1. Bit 3 is set to 0, the window is hidden. 


2. Bit 3 is set to 1, the window is not hidden (but will not be 
displayed on the screen, because the display is enlarged). 


— Bit 6 set to 0 means that the session is not displayed in the base 
colors. 
Bit 6 set to 1 means that the session is displayed in the base 
colors. 


— Bit 7 set to 0 means that the session is not displayed in the 
foreground and background colors. 
Bit 7 set to 1 means that the session is displayed in the 
foreground and background colors. 


Note: Bits 6 and 7 cannot both be set to 1. 


Change Window Attributes 


e “Row on PS” is the row position of the upper left corner of the window 
on the presentation space. 


e “Column on PS” is the column position of the upper left corner of the 
window on the presentation space. 


Return Codes 
e System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


e Window Management Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the window management portion of the workstation program. The 
function ID is in byte 1, and the error number is in byte 0. Window 
management return codes use a function ID of X‘63’. The error codes 
that can be received for this service are: 


Code Meaning 


X‘00° Successful completion. 

X‘02’ Invalid session ID. 

X‘04’ The session is not connected for window management 
services. 

X‘06’ Invalid screen ID. 

X‘07° The window is not found on screen. 

X‘0C’ Byte 0 of the parameter list is not zero on request. 

X‘0E’ No windows exist on screen. 

X‘11’ One or more values sent in the parameter list are not valid. 


See Appendix H, “Return Codes,” for more information. 


Usage Notes 


e If the window does not exist on the specified screen, it is added to the 
screen, with the attributes specified in the parameter list. 


e A value of 0 for either the number of rows or the number of columns in 
the window size is changed by the workstation program to a value of 1. 


e Ifthe window overlaps the screen or presentation space boundaries 
after it has been moved to the new position: 


— The window is moved to fit on the screen. 
— A return code of X‘11’ is returned in the parameter list. 


— The row and column numbers of the window position chosen by the 
workstation program are returned in the parameter list. 
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oe =e Se 


CTRETNCD 
CTFXNID 

CTSESSID 
CTSCRPRO 
CTWINDN 

CTROWNUM 
CTCOLNUM 
CTROWSCR 
CTCOLSCR 


CTWINDCO 
CTBORDCO 
CTFLAG 
CTROWPS 
CTCOLPS 


O0000 


oaoo0o00 0000 


If the window overlaps the screen boundaries after it has been changed 
to the new size: 


— The window is moved to fit on the screen. 


— A return code of X‘1l’ is returned in the parameter list. 


If the window is too big to fit on the screen after it has been changed to 
the new size: 


— The window size is reduced, and the window position is changed (if 
necessary), to allow the window to fit on the screen. 


— Areturn code of X‘1l’ is returned in the parameter list. 


— The number of rows and columns in the window size chosen by the 
workstation program is returned in the parameter list. 


If the “hidden” bit in the control flag is 1 and the window is the only 
window on the screen, the workstation program changes the bit setting 
to 0. 


If the “hidden” bit in the control flag is 1 and all the other windows on 
the specified screen profile are hidden, then the next window on the 
chain will become not hidden and will be made the active window. 


If any of the reserved bits in the control flag are set to 1, the 
workstation program changes the bit setting to 0. 


If both the “base colors” and “window colors” bits in the control flag 
are the same value (both 1 or both 0), “base colors” is used as the 
default setting. 


This service places the specified window at the bottom of the chain on 
the specified screen profile. 


PARAMETER LIST FOR CHANGE WINDOW ATTRIBUTES 


RETURN CODE 

FUNCTION ID 

SESSION ID 

SCREEN PROFILE NUMBER IN ASCII 
WINDOW SHORT NAME IN ASCII 

NUMBER OF ROWS IN THE WINDOW 
NUMBER OF COLUMNS IN THE WINDOW 
ROW NUMBER AND COLUMN NUMBER OF THE 
UPPER LEFT CORNER OF THE WINDOW 

ON THE SCREEN 

WINDOW COLOR ATTRIBUTES 

BORDER COLOR ATTRIBUTES 

FLAG BYTE 

ROW AND COLUMN NUMBER OF THE UPPER 
LEFT CORNER OF THE WINDOW ON THE 
PRESENTATION SPACE 


i, i i i i il Bl al El a Sl ad Sl al LD 


~e te Ne 


=e Me Ne 


ue Ne Ne 


Change Window Attributes 


INITIALIZE PARAMETER LIST FOR CHANGE WINDOW ATTRIBUTES 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


MOV 
MOV 


MOV 
MOV 
MOV 


CTRETNCD , OOH 
CTFXNID, 00H 
AL,SESSID 
CTSESSID,AL 
AL, ‘1! 
CTSCRPRO,AL 
AL,'P' 
CTWINDN , AL 
AL,10 
CTROWNUM, AL 
AL,10 
CTCOLNUM, AL 
AL,15 
CTROWSCR,AL 
AL,15 
CTCOLSCR, AL 
AL ,00001000B 
CTWINDCO,AL 
AL ,O 
CTBORDCO,AL 
AL,00000001B 
CTFLAG, AL 


CTROWPS, AL 


AL,5 
CTCOLPS , AL 
CTROWPS , AL 


Ct en eT eT | ee eT | eT et eT | eT eT r,t | | eT a) a) a |) | a | |) TY 


RETURN CODE MUST O BEFORE REQUEST 
FUNCTION ID MUST = O BEFORE REQUEST 
SESSION ID OBTAINED FROM REQUEST 

TO QUERY SESSION ID 

SCREEN PROFILE NUMBER 

IN PARAMETER LIST 

WINDOW SHORT NAME 

IN PARAMETER LIST 

NUMBER OF ROWS IN THE NEW 

WINDOW SIZE 

NUMBER OF COLUMNS IN THE 

WINDOW SIZE 

ROW NUMBER AND COLUMN NUMBER OF THE 
UPPER LEFT CORNER OF THE 

WINDOW ON SCREEN 

IN THE PARAMETER LIST 

FOREGROUND = BLUE AND 

BACKGROUND = BLACK 

BORDER COLOR WILL BE THE SAME 

AS THE WINDOW COLOR 

THE SESSION IS NOT HIDDEN AND IT 

IS DISPLAYED IN FOREGROUND AND 
BACKGROUND COLORS 

ROW NUMBER OF UPPER LEFT CORNER 

OF THE WINDOW 

ON THE PRESENTATION SPACE 

COLUMN NUMBER OF UPPER LEFT CORNER 
OF THE WINDOW 

OF THE WINDOW 


INITIALIZE REGISTERS FOR CHANGE WINDOW ATTRIBUTES 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


AH,O9H 
AL, 1BH 
BH, 80H 
BL, 20H 
CX, OFFH 
DX ,WSCTRL 


DI, SEG CTRETNCD 


ES,DI 


DI,OFFSET CTRETNCD 


. 
, 
° 
, 
° 
a 
° 
cf 


RESOLVED VALUE FOR WSCTRL 

SEGMENT ADDRESS OF PARAMETER LIST 
IN ES 

OFFSET OF PARAMETER LIST IN DI 


SIGNAL WORKSTATION PROGRAM FOR CHANGE WINDOW ATTRIBUTES SERVICE 


INT 


7AH 
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Select Active Screen 


Window Management Service X‘1C’: Select Active 
Screen 


Use this service to make the specified screen profile the active screen. 


Register Values 


On Request On Completion 

AH = X‘09’ CH = X‘12’ 

AL = X‘1C’ CL = Return code 

BH = X‘80’ 

BL = X‘20’ The contents of registers 
CX = X‘OOFF’ AX, BX, DX, ES, and DI 
DX Resolved value for WSCTRL are unpredictable. 


ES = Segment address of the parameter list 
DI = Offset address of the parameter list 


Parameter List Format 


Contents Contents 
Offset Length on Request on Completion 


fo‘ byte 


1 1 byte Must be zero Function ID 
(X‘63’) 


Unchanged 


3 1 byte Screen profile Unchanged 
number 


Parameter Definitions 


Request Parameters: 


e The session ID is the ID of the session currently connected to the work 
station control session. 


e The screen profile number is the number (in ASCII) of the screen profile 
being made active. 
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Select Active Screen 


Return Codes 
e System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


e Window Management Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the window management portion of the workstation program. The 
function ID is in byte 1, and the error number is in byte 0. Window 
management return codes use a function ID of X‘63’. The error codes 
that can be received for this service are: 


Code Meaning 


X‘00’ Successful completion. 

X‘02’ Invalid session ID. . 

X‘04’ The session is not connected for window management 
services. 

X‘06’ Invalid screen ID. 

X‘0C’ Byte 0 of the parameter list is not zero on request. 


See Appendix H, “Return Codes,” for more information. 
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e 
’ 


. 
’ 


’ 

ASRETNCD DB 
ASFXNID DB 
ASSESSID DB 
ASSCREEN DB 


7 


° 
, 
. 
f 


° 
i 


OO00 


PARAMETER LIST FOR SELECT ACTIVE 


SCREEN 


me Me Ne NO 


RETURN CODE 
FUNCTION NUMBER 
SESSION ID 
SCREEN NUMBER 


INITIALIZE PARAMETER LIST FOR SELECT ACTIVE SCREEN 


MOV 
MOV 
MOV 
MOV 
MOV 


ASRETNCD , 00H 
ASFXNID, 00H 
AL,SESSID 
ASSESSID,AL 
ASSCREEN , 3 


° 
‘ 
° 
, 
° 
r 


° 
, 


RETURN CODE MUST = O BEFORE REQUEST 
FUNCTION ID MUST = O BEFORE REQUEST 
SESSION ID INTO THE LIST 


SCREEN NUMBER 3 


INITIALIZE REGISTERS FOR SELECT ACTIVE SCREEN 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


AH, 09H 

AL,1CH 

BH, 80H 

BL, 20H 

CX, OF FH 
DX,SERVTYPE 

DI, SEG ASRETNCD 
ES,DI 

DI,OFFSET ASRETNCD 


° 
a, 
. 
c 
e 
tA 
° 
tf 


SERVICE TYPE IN DX 

SEGMENT ADDRESS OF PARAMETER LIST 
IN ES 

OFFSET OF PARAMETER LIST IN DI 


SIGNAL WORKSTATION PROGRAM FOR SELECT ACTIVE SCREEN SERVICE 


INT 


7AH 


Select Active Screen 
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Introduction 


This chapter describes how to code requests for the host interactive services 
provided by the API. 


The host interactive services allow communication between a personal 
computer application program and a host application program using 
destination/origin structured field protocol. The host interactive services 
also allow a personal computer application program to be notified when a 
host presentation space or operator information area is updated. 


With CUT host sessions, one connection is allowed for only PS/OIA 
updates. For each DFT host session, all PC tasks may connect for both 
destination/origin and PS/OIA updates; however, a maximum of three 
connections at any one time are allowed. When destination/origin 
protocols are used, each PC task must be identified with a unique 
application name. When activated, the 3270 PC file transfer program uses 
one of the three connections. With the destination/origin protocol, the 3270 
Workstation Program accepts Open (X‘D000’), Close (X‘D041’), Set Cursor 
(X‘D045’), Get (X‘D046’), and Insert and Insert Data structured fields 
(X‘D047’). See Appendix B, aa bea Structured Fields,” for 
more information. 


The host interactive services provided by the API are: 


e Connect to Host Session Service: Use this service to connect to the 
specified host session for host interactive services. 


e Disconnect from Host Session Service: Use this service to 
disconnect from the specified host session. 


e Read Structured Field Service: Use this service to read structured 
field data from the specified host session. This service is valid for DFT 
host sessions only. 


e Write Structured Field Service: Use this service to write 
structured field data to the specified host session. This service is valid 
for DFT host sessions only. 


e Define Buffer Service: Use this service to define a buffer that will 
be used to receive a message from the specified host session. This 
service is valid for DFT host sessions only. 


Requesting the Host Interactive Services 


7-2 


To request any of the host interactive services, load the registers and the 
parameter list with the proper values, and use the INT 7AH instruction to 
signal the workstation program that it has a request to process. 


Note: Before your application can request the host interactive services, it 
must request the Name Resolution service, using ‘MFIC * as the 
gate name in the parameter list. (Remember that the gate name must 
be padded to the right with blanks if it is less than eight characters.) 


Introduction 


Return Codes for the Host Interactive Services 


Each host interactive service has two return codes associated with it: a 
system return code and a host interaction management return code. Both 
types of return codes are 2-byte values made up of a function ID and an 
error number. The function ID indicates the portion of the workstation 
program in which the error occurred. The error number indicates the 
specific type of error that has occurred. An error number of X‘00’ always 
indicates a successful acceptance or completion of the request. 


System Return Codes: 


After your application has requested a host interactive service, the CH 
and CL registers contain a return code generated by the request 
processing portion of the workstation program. The function ID is in 
the CH register, and the error number is in the CL register. System 
return codes use a function ID of X‘12’. The error codes that can 
appear are: 


Code Meaning 


X‘00° Request accepted. 

X‘05’ Invalid index specified. 
X‘07’ Invalid reply specified. 
X‘08’ Invalid wait type specified. 
X‘0B’ RQE pool depleted. 

X‘OF’ Invalid environment access. 
X‘34’ Invalid gate entry. 


These system return codes apply to all host interactive services. 
Host Interactive Services Return Codes: 


After a requested host interactive service is completed, bytes 0 and 1 of 
the parameter list contain a return code generated by the host 
interaction management portion of the Workstation Program. The 
function ID is in byte 1, and the error number is in byte 0. Host 
interactive return codes use a function ID of X‘32’. The error numbers 
that can appear are specific to the service that was requested and are 
included in the descriptions of each service. 


See Appendix H, “Return Codes,” for more information. 
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Host Interactive Service X‘01’: Connect to Host Session 


Register Values 


Use this service to connect to the specified host session for host interactive 
services. 


On Request On Completion 
AH = X‘09’ AX = Request ID 
AL = X‘0I CH = X‘12’ 

BH = Synchronous or asynchronous * CL = Return code 
BL = Synchronous or asynchronous * 

CX = X*‘0000’ The contents of 

DX = Resolved value for MFIC registers BH, DX, 
ES = Segment address of the parameter list ES, and DI are 

DI = Offset address of the parameter list unpredictable. 


* The values in these registers depend on whether you want the request to be processed 
synchronously or asynchronously. See the following description of request register values 
for more information. 


e Request Register Values: 


You can specify synchronous or asynchronous processing of the 
Connect to Host Session service. In synchronous processing, control is 
returned to your application program after the workstation program has 
completed the request. In asynchronous processing, control is returned 
to your application program before the workstation program has 
completed the request. You must use the Get Request Completion 
service to obtain the parameter list values on completion when you 
request asynchronous processing. 


Synchronous processing: 
There are two ways to specify synchronous processing: 


1. Set the BH register to X‘80’ and the BL register to X‘20’. When the 
request is completed, control is returned to your application 
program, and the registers and parameter list contain the values for 
completion of the request. 


2. Set both the BH and BL registers to X‘40’. When the request is 
completed, control is returned to your program, but the parameter 
list values for completion of the request are not obtained until you 
request the Get Request Completion service. 


Connect to Host Session 


Asynchronous processing: 


For asynchronous processing of the Connect to Host Session service 
request, set the BH register to X‘40’ and the BL register to X‘00’. When 
asynchronous processing is specified, you must request the Get Request 
Completion service to obtain the results of the Connect to Host Session 
service. 


e Completion Register Values: 


If you specified asynchronous processing, or synchronous processing 
using X‘40’ in both the BH and BL registers on request, the AX register 
contains a request ID that the workstation program assigned to the 
request. Match this request ID with the results from the Get Request 
Completion service. 


Parameter List Format to Connect for Structured Field Communications 


Note: Connection for structured field communication is valid for DFT host 
sessions only. 


FS 
Offset | Length on Request on Completion 

fo _[ibyte | Must be zero ——‘([ Return code 
| 


10 1 word Offset address of Unchanged 
Query Reply data 

12 1 word Segment address of Unchanged 
Query Reply data 

Task ID Unchanged 


20 — 96 
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Request Parameters: 


For connect for structured field communications: 


The session ID is the ID of the host session you will be communicating 
with using structured fields. 


The fixed-length queue ID is the ID of a fixed-length queue that the 
workstation program will use to post communication status information 
about the specified host session. Your application program must use 
the Dequeue Data service to obtain the communication status 
information before each Read Structured Field service request. The 
communication status information is described under “Usage Notes” in 
the Read Structured Field service description in this chapter. 


The format of the Query Reply data is as follows: 


Up to maximum | Maximum number of bytes 
of X‘OE00’ allowed in an inbound 
transmission 


Up to maximum | Maximum number of bytes 
of X‘0E00’ allowed in an outbound 
transmission 


Must be X‘OF’ Identifies the next two bytes as 
being the destination/origin ID 

Must be zero Destination/origin ID supplied 
by the 3270 workstation 
program 


The task ID is the ID of the task that is issuing the Connect to Host 
Session service request. It is used to identify the application to the API 
and must be the same for all Read Structured Field, Write Structured 
Field, and Define Buffer services that your application program 
requests. You can use the Query Active Task service to obtain the ID 
of your application program. The Query Active Task service is 
described in Chapter 17, “Coding Task State Modifier Services.” 


The system work area is used by the workstation program while it 
processes the request. This area must be provided in the parameter list. 


Connect to Host Session 


Parameter List Format to Connect for PS/OIA Update Events 


Note: Connection for PS/OIA update events is valid for both DFT and CUT 


host sessions. 


Poe a 
Offset | Length on Request on Completion 
}o | ibyte | Must bezero | Returncode 


Unchanged 
Fixed-length queue ID 


Parameter Definitions 
Request Parameters: 
For connect for PS/OIA update events: 


e The session ID is the ID of the host session for which you want to 
receive notification whenever PS/OIA information is updated. The 
session ID is one word in length. 


e The fixed-length queue ID is the ID of a fixed-length queue that the 
workstation program will use to post update information about the 
PS/OIA of the specified host session. Your application program must 
use the Dequeue Data service to obtain the update information. The 
Dequeue Data service is described in Chapter 3, “Coding Supervisor 
Services.” The format of the update information is in 4 bytes, 2 for the 
session ID and 2 for the update information. The update information is 
as follows: 


— ‘1000’ - Presentation space updated 


— X*2000’ - OIA updated 
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The events that you want to be notified of are specified as follows: 


|Bitso- 4 [Bits [Bite | Bit7 | 
[Must be zero [PS [OIA | Must be zero _| 


— Bits 0 through 4 are reserved and must be zero. 

~ Bit 5 set to 1 indicates that you want to be notified of presentation 
space updates to the specified host session. 

— Bit 6 set to 1 indicates that you want to be notified of operator 
information area updates to the specified host session. 

— Bit 71s reserved and must be zero. 


The system work area is used by the workstation program while it 
processes the request. This area must be provided in the parameter list. 


System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


Host Interactive Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the host interaction management portion of the workstation program. 
The function ID is in byte 1, and the error number is in byte 0. Host 
interactive return codes use a function ID of X‘32’. The error codes that 
can be received for this service are: 


Code Meaning 


X‘00’ Successful completion. 

X‘01’ The host session is not active (DFT only). 

X‘02’ Invalid service request parameter. 

X‘04’ The session is already connected. 

X‘08’ A system error has occurred. 

X‘10’ The limit of three requesters have already connected. 
X‘0C’ Byte 0 of the parameter list is not zero on request. 


See Appendix H, “Return Codes,” for more information. 


Connect to Host Session 


Usage Notes 


e Before you request this service, you must create a fixed-length queue 
entry using the Create Queue service. 


e Ifyou specified asynchronous processing, or synchronous processing 
using X‘40’ in both the BH and BL registers on request, you must use 
the Get Request Completion service to obtain the results in the 
parameter list when the Connect to Host Session service is completed. 


e CUT host sessions can be connected to for PS/OIA update events only, 
not structured field communications. 


Chapter 7. Coding Host Interactive Service Requests 17-9 


Connect to Host Session 


Coding Example 


. 
’ 


; PARAMETER LIST FOR CONNECT TO HOST SESSION 


CFRETNCD DB 
CFFXNID DB 
CFSESSID DB 


RETURN CODE 
FUNCTION NUMBER 
SESSION ID 


~e te Ne Ne 


CFRESRV1 DB MUST BE O 
CFFLQID DB ; FIXED-LENGTH QUEUE ID MUST BE O01 
DB 
CFEVNTS DB 00 ; EVENTS TO BE ENQUEUED - DFT 
DB 06 
CFQRPLY DD QUERYREP ; OFFSET AND SEGMENT OF THE QUERY REPLY 
CFRESERV2 DW ¢) ; MUST BE O 
CFTASKID DW @) > PC TASK ID 
CFRESRV3 DW 0 ; MUST BE O 
CFWORK DW 9 DUP(0) ; SYSTEM WORK AREA 


. 
, 


; QUERY REPLY FOR DESTINATION/ORIGIN 


QUERYREP DW 0019H 


LENGTH OF THE STRUCTURE 
DB 81H QUERY REPLY 
DB DH ANOMALY IMPLEMENTATION 
DB 0 MUST BE O 


DW 0008H MAXIMUM NUMBER OF BYTES IN INBOUND TRANSMISSION 


7 
; 

DB O1H 7 STRUCTURED FIELD EXCHANGE 

DW 0008H ; MAXIMUM NUMBER OF BYTES IN OUTBOUND TRANSMISSION 
, 


DB OFH RESERVED 
DW 0 RESERVED 
PC APPLICATION NAME IN EBCDIC 


QRAPLNAM DB 8 DUP(0) 


; INITIALIZE PARAMETER LIST FOR CONNECT TO HOST SESSION 


MOV CFRETNCD,0OH ; RETURN CODE MUST = 0 BEFORE REQUEST 
MOV CFFXNID,OOH ; FUNCTION ID MUST = 0 BEFORE REQUEST 
MOV AL,SESSID ; SESSION ID INTO THE LIST | 
MOV CFSESSID,AL 

MOV AX,QUEUEID ; FIXED-LENGTH QUEUE ID INTO THE LIST 
MOV CFFLOQID,AX 

MOV AX,PCTASKID ; PC TASK ID INTO THE LIST 


MOV CFTASKID,AX 


INITIALIZE REGISTERS FOR CONNECT TO HOST SESSION 


=e te Ne 


MOV AH,09H 
MOV AL,O1H 
MOV BH,80H 
MOV BL,20H 
MOV CX,OFFH 
MOV DX,SERVTYPE ; RESOLVED VALUE FOR 'MFIC 
MOV DI, SEG CFRETNCD ; SEGMENT ADDRESS OF PARAMETER LIST 
MOV ES,DI ; IN ES 
MOV DI,OFFSET CFRETNCD ; OFFSET OF PARAMETER LIST IN DI 
: SIGNAL WORKSTATION PROGRAM FOR CONNECT TO HOST SESSION SERVICE 


INT 7AH 
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Disconnect from Host Session 


Host Interactive Service X‘02’: Disconnect from Host 


Session 


Register Values 


Use this service to disconnect from the specified host session. 


On Request . On Completion 
AH = X‘09’ AX = Request ID 
AL = X‘02’ CH = X‘12’ 

BH = Synchronous or asynchronous * CL = Return code 
BL = Synchronous or asynchronous * 

CX = X‘0000’ The contents of 

DX = Resolved value for MFIC registers BH, DX, 
ES = Segment address of the parameter list ES, and DI are 

DI = Offset address of the parameter list unpredictable. 


* The values in these registers depend on whether you want the request to be processed 
synchronously or asynchronously. See the following description of request register values 
for more information. 


e Request Register Values: 


You can specify synchronous or asynchronous processing of the 
Disconnect from Host Session service. In synchronous processing, 
control is returned to your application program after the workstation 
program has completed the request. In asynchronous processing, 
control is returned to your application program before the workstation 
program has completed the request. You must use the Get Request 
Completion service to obtain the parameter list values on completion 
when you request asynchronous processing. 


Synchronous Processing: 
There are two ways to specify synchronous processing: 


1. Set the BH register to X‘80’ and the BL register to X‘20’. When the 
request is completed, control is returned to your application . 
program, and the registers and parameter list contain the values for 
completion of the request. 


2. Set both the BH and BL registers to X‘40’. When the request is 
completed, control is returned to your program, but the parameter 
list values for completion of the request are not obtained until you 
request the Get Request Completion service. 
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Disconnect from Host Session 


Asynchronous Processing: 


For asynchronous processing of the Disconnect from Host Session 
service request, set the BH register to X‘40’ and the BL register to X‘00’. 
When asynchronous processing is specified, you must request the Get 
Request Completion service to obtain the results of the Disconnect from 
Host Session service. 


e Completion Register Values: 


If you specified asynchronous processing, or synchronous processing 
using X‘40’ in both the BH and BL registers on request, the AX register 
contains a request ID that the workstation program assigned to the 
request. You use this request ID to match the results of the service 
obtained by the Get Request Completion service to the results of this 
service. That is, when the request ID in the AX register on completion 
of the Get Request Completion service, matches the request ID in the 
AX register on completion of this service, the results obtained by the 
Get Request Completion service pertain to this request. 


Parameter List Format 
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one Jags [Stain [Ss 
Offset | Length on Request on Completion 

jo ibyte | Must be zero | Returncode 
}6__—{ibyte | Disconnect type | Unchanged 
[8 sf iword [Reserved si Reserved 
20 — 35 


Disconnect from Host Session 


Parameter Definitions 


Return Codes 


Usage Notes 


Request Parameters: 


The session ID is the ID of the host session to disconnect from. 
The disconnect type is specified as follows: 


— X‘01’ to disconnect for structured field communications 
— X‘03’ to disconnect for PS/OIA update events 


Note: Disconnect type X‘01’ can be specified for DFT host sessions only. 
Disconnect type X‘03’ can be specified for both DFT and CUT host 
sessions. 


The system work area is used by the workstation program while it 
processes the request. This area must be provided in the parameter list. 


System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


Host Interactive Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the host interaction management portion of the workstation program. 
The function ID is in byte 1, and the error number is in byte 0. Host 
interactive return codes use a function ID of X‘32’. The error codes that 
can be received for this service are: 


Code Meaning 


X‘00’ Successful completion. 

X‘02’ Invalid service request parameter. 

X‘04’ The session is not connected. 

X‘08’ A system error has occurred. 

X‘0C’ Byte 0 of the parameter list is not zero on request. 


See Appendix H, “Return Codes,” for more information. 


If you specified asynchronous processing, or synchronous processing 
using X‘40’ in both the BH and BL registers on request, you must use 
the Get Request Completion service to obtain the results in the 
parameter list when the Disconnect from Host Session service is 
completed. 
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Disconnect from Host Session 


Coding Example 
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e 
f 


e 
a, 


PARAMETER LIST FOR DISCONNECT FROM 


DFRETNCD DB 


DFFXNID DB 
DFSESSID DB 
DFRESERV1 DB 
DW 
DFTYPE DB 
DW 


DFWORK DW 


, 


’ 


° 
a 


° 
, 


° 
, 


0 
) 
0 
0 
0 
O01 
6 


2 


DUP (0) 
DUP (0) 


Pt a et St eT a eT 


HOST SESSION 


RETURN CODE 

FUNCTION NUMBER 

SESSION ID 

RESERVED 

NOT USED 

DISCONNECT TYPE - DESTINATION/ORIGIN 
NOT USED 

SYSTEM WORK AREA 


INITIALIZE PARAMETER LIST FOR DISCONNECT FROM HOST SESSION 


MOV 
MOV 
MOV 
MOV 


DFRETNCD, OOH 
DFFXNID,00H 
AL,SESSID 

DFSESSID,AL 


. 
a 
° 
f 
° 
tf 


RETURN CODE MUST O BEFORE REQUEST 
FUNCTION ID MUST QO BEFORE REQUEST 
SESSION ID INTO THE LIST 


INITIALIZE REGISTERS FOR DISCONNECT FROM HOST SESSION 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


AH, 09H 
AL,02H 

BH, 80H 

BL, 20H 

CX, OFFH 

DX ,SERVTYPE 

DI, SEG DFRETNCD 
ES,DI 

DI,OFFSET DFRETNCD 


e 
, 
. 
cf 
e 
f 
« 
, 


RESOLVED VALUE FOR 'MFIC : 

SEGMENT ADDRESS OF PARAMETER LIST 
IN ES 

OFFSET OF PARAMETER LIST IN DI 


SIGNAL WORKSTATION PROGRAM FOR DISCONNECT FROM HOST SESSION SERVICE 


INT 


7AH 


Read Structured Field 


Host Interactive Service X‘03°: Read Structured Field 


Register Values 


Use this service to read structured field data from the specified host 
session. This service is valid for DFT host sessions only. 


On Request On Completion 
AH = X‘09’ AX = Request ID 
AL = X‘03’ CH = X‘12’ 

BH = Synchronous or asynchronous * CL = Return code 
BL = Synchronous or asynchronous * 

CX = X‘0000’ The contents of 

DX = Resolved value for MFIC registers BH, DX, 
ES = Segment address of the parameter list ES, and DI are 

DI = Offset address of the parameter list unpredictable. 


* The values in these registers depend on whether you want the request to be processed 
synchronously or asynchronously. See the following description of request register values 
for more information. 


e Request Register Values: 


You can specify synchronous or asynchronous processing of the Read 
Structured Field service. In synchronous processing, control is 
returned to your application program after the workstation program has 
completed the request. In asynchronous processing, control is returned 
to your application program before the workstation program has 
completed the request. You must use the Get Request Completion 
service to obtain the parameter list values on completion when you 
request asynchronous processing. 


Synchronous Processing: 
There are two ways to specify synchronous processing: 


1. Set the BH register to X‘80’ and the BL register to X‘20’. When the 
request is completed, control is returned to your application 
program and the registers and parameter list contain the values for 
completion of the request. 


2. Set both the BH and BL registers to X‘40’. When the request is 
completed, control is returned to your program, but the parameter 
list values for completion of the request are not obtained until you 
request the Get Request Completion service. 
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Read Structured Field 


Asynchronous Processing: 


For asynchronous processing of the Read Structured Field service 
request, set the BH register to X‘40’ and the BL register to X‘00’. When 
asynchronous processing is specified, you must request the Get Request 
Completion service to obtain the results of the Read Structured Field 
service. 


e Completion Register Values: 


If you specified asynchronous processing, or synchronous processing 
using X‘40’ in both the BH and BL registers on request, the AX register 
contains a request ID that the workstation program assigned to the 
request. You use this request ID to match the results of the service 
obtained by the Get Request Completion service to the results of this 
service. That is, when the request ID in the AX register on completion 
of the Get Request Completion service matches the request ID in the AX 
register on completion of this service, the results obtained by the Get 
Request Completion service pertain to this request. 


Parameter List Format 
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ons [ies [eie [eine 
Offset | Length on Request on Completion 

fo [1byte | Must be zero—*([Retun code 
2 [i byte | Host session 1D ___| Unchanged 
[s__|ibyte | Must be zero ‘| Unchanged 
16 {ibyte [xo Unchanged 
etc 


10 1 word Unchanged Offset address of 
structured field data 
12 1 word Unchanged Segment address of 
structured field data 
Task ID Unchanged 


20 — System work area 


Read Structured Field 


Parameter Definitions 
Request Parameters: 


e The session ID is the ID of the host session to read the structured field 
data from. 


e The task ID must be the same task ID that was specified by the 
application program in the parameter list for the Connect to Host 
Session service. 


e The system work area is used by the workstation program while it 
processes the request. This area must be provided in the parameter list. 


Completion Parameters: 


e The structured field data contains the application structured fields 
received from the host. Destination/origin structured field headers are 
removed by the workstation program before the structured field data 
reaches the application. 


The structured field data format is as follows: 


1 word m (message length, which is the number of 
bytes in the message). This length does not 
include the eight bytes used for the message 
buffer header. 
1 word n (buffer size - this is the number that you 
specified in the Define Buffer request). 
6000 


2 
1 word p Number of bytes from byte 8 to the end of 
the message. . 


1 byte First byte in the structured field message 
1 byte Second byte in the structured field message 


lm —s [byte Last byte in the structured field message 


Bytes 0 through 7 are the buffer header. Bytes 8 and 9 contain the number 
of bytes in the message, including 2 bytes for bytes 8 and 9. Bytes 10 
through m are used for the structured field message received from the host. 
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Read Structured Field 


Return Codes 


Usage Notes 
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System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


Host Interactive Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the host interaction management portion of the workstation program. 
The function ID is in byte 1, and the error number is in byte 0. Host 
interactive return codes use a function ID of X‘32’. The error codes that 
can be received for this service are: 


Code Meaning 


X‘00’ Successful completion. Structured field data is available in 
the message buffer. 

X‘02’ Invalid service request parameter. 

X‘04’ The session is not connected. 

X‘08’ A system error has occurred. 

X‘0C’ Byte 0 of the parameter list is not zero on request. 


X‘14’ No structured field data is available. 


See Appendix H, “Return Codes,” for more information. 


If you specified asynchronous processing, or synchronous processing 
using X‘40’ in both the BH and BL registers on request, you must use 
the Get Request Completion service to obtain the results in the 

parameter list when the Read Structured Fields service is completed. 


Before you request the Read Structured Field service, you must use the 
Dequeue Data service to check for the communication status 
information that indicates that a message is available from the host. 


The first two bytes of the communication status information contain the 
session ID of the host session that the information pertains to. The 
second two bytes of the communication status information contain one 
of the following codes: 


Code Type Meaning 


X‘04’ X‘80’ A message from the host is available. 

X‘06’ X‘80’ An outbound transmission from the host was 
canceled. 

X‘08’ X‘00’ Lost contact with the host. 

X‘0A’ X‘00’ Contact reestablished with the host. 


Coding Example 


° 
‘ 


° 
t 


PARAMETER LIST FOR READ STRUCTURED 


RSRETNCD DB 


RSFXNID DB 
RSHOSTID DB 
RSZERO DB 
DW 
DB 
DB 
RSOFFSD DW 
RSSEGTD DW 
DW 
RSTASKID DW 
DW 
DW 


° 
L 


° 
U 


r 


. 
’ 
° 
t 


. 
t 


0 
0 
0 
0 
0 
Os 
00 
e) 
0 
0 
0 
e) 
9 


DUP (0) 


i a eT Mt eT MT Sl a Mt MT | 


~e 


INITIALIZE PARAMETER LIST FOR READ 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


RSRETNCD, OOH 
RSFXNID,OOH 
AL,HOSTID 
RSHOSTID, AL 
AX,PCTSKID 
RSTASKID,AX 
RSZERO,O 


et et et eT eT TY 


Read Structured Field 


FIELD 


RETURN CODE 

FUNCTION NUMBER 

HOST SESSION ID 

UNCHANGED 

NOT USED 

STRUCTURED FIELD TYPE, (DEST/ORIG) 
UNUSED 

OFFSET ADDRESS OF STRUCTURED FIELD DATA 
SEGMENT ADDRESS OF STRUCTURED FIELD DATA 
UNUSED 

PC TASK ID 


SYSTEM WORK AREA 


STRUCTURED FIELD 


RSRETNCD MUST BE O BEFORE REQUEST 
RSFXNID MUST BE O BEFORE REQUEST 
HOST ID IN 

THE LIST 
PC TASK ID 

IN LIST 
THIS FIELD MUST BE ZEROED 


INITIALIZE REGISTERS FOR READ STRUCTURED FIELD 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


AH ,O9H 

AL ,03H 

BH, 40H 

BL, 40H 

Cx,0 

DX ,MFIC 

DI, SEG RSRETNCD 
ES,DI 

DI,OFFSET RSRETNCD 


. 
a 
° 
i 
Ul 
. 
a 
. 
Z 
’ 
‘ 


REPLY TYPE IN BH 

WAIT TYPE IN BL 

PRIORITY IN CX 

RESOLVED VALUE FOR 'MFIC : 

SEGMENT ADDRESS OF PARAMETER LIST 
IN ES 

OFFSET OF PARAMETER LIST IN DI 


SIGNAL WORKSTATION PROGRAM FOR READ STRUCTURED FIELD SERVICE 


INT 


7AH 
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Write Structured Field 


Host Interactive Service X‘04’: Write Structured Field 


Register Values 


7-20 


Use this service to write structured field data to the specified host session. 


This service is valid for DFT host sessions only. 


On Request 

AH = X‘09’ 

AL = X04 

BH = Synchronous or asynchronous * 

BL = Synchronous or asynchronous * 

CX = X‘0000’ 

DX = Resolved value for MFIC 

ES = Segment address of the parameter list 
DI = Offset address of the parameter list 


On Completion 


AX = Request ID 
CH = X‘12’ 
CL = Return code 


The contents of 
registers BH, DX, 
ES, and DI are 
unpredictable. 


* The values in these registers depend on whether you want the request to be processed 
synchronously or asynchronously. See the following description of request register values 


for more information. 


e Request Register Values: 


You can specify synchronous or asynchronous processing of the Write 
Structured Field service. In synchronous processing, control is 
returned to your application program after the workstation program has 
completed the request. In asynchronous processing, control is returned 
to your application program before the workstation program has 
completed the request. You must use the Get Request Completion 
service to obtain the parameter list values on completion when you 


request asynchronous processing. 


Synchronous Processing: 


There are two ways to specify synchronous processing: 


1. Set the BH register to X‘80’ and the BL register to X‘20’. When the 
request is completed, control is returned to your application 
program, and the registers and parameter list contain the values for 


completion of the request. 


2. Set both the BH and BL registers to X‘40’. When the request is 
completed, control is returned to your program, but the parameter 
list values for completion of the request are not obtained until you 


request the Get Request Completion service. 


Write Structured Field 


Asynchronous Processing: 


For asynchronous processing of the Write Structured Field service 
request, set the BH register to X‘40’ and the BL register to X‘00’. When 
asynchronous processing is specified, you must request the Get Request 
Completion service to obtain the results of the Write Structured Field 
service. 


e Completion Register Values: 


If you specified asynchronous processing, or synchronous processing 
using X‘40’ in both the BH and BL registers on request, the AX register 
contains a request ID that the workstation program assigned to the 
request. You use this request ID to match the results of the service 
obtained by the Get Request Completion service to the results of this 
service. That is, when the request ID in the AX register on completion 
of the Get Request Completion service matches the request ID in the AX 
register on completion of this service, the results obtained by the Get 
Request Completion service pertain to this request. 


Parameter List Format 


on [un [Sin (Stes 
Offset | Length on Request on Completion 

[fo [1tyte | Must be zero —~—~=*drReturn code id 
(6 [itye [xor—~—~S~*d Unchanged 
fs [iword [Reserved ~~‘ Reserved 


10 1 word Offset address of Unchanged 
structured field data 

12 1 word Segment address of Unchanged 
structured field data 

Task ID Unchanged 


20 — 35 System work area System work area 
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Write Structured Field 


Parameter Definitions 


Request Parameters: 


The session ID is the ID of the host session to write the structured field 
data to. 


The task ID must be the same task ID that was specified by the 
application program in the parameter list for the Connect to Host 
Session service. 


The structured field data contains the application structured fields that 
are to be sent to the host. Destination/origin structured fields are 
added by the workstation program before the structured field data 
reaches the host. 


The system work area is used by the Workstation Program while it 
processes the request. This area must be provided in the parameter list. 


The structured field data format is as follows: 


m (message length, which is the number of 
bytes in the message). This length does not 
include the eight bytes used for the message 
buffer header. 


Second byte in the structured field message 
must be X‘00’, X‘41’, X‘45’, X‘46’, X‘47’, and 


Bytes 0 through 7 are the buffer header. Bytes 8 and 9 contain the number 
of bytes in the message, including 2 bytes for bytes 8 and 9. Bytes 10 
through m + 7 are used for the structured field message sent to the host. 
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Return Codes 


Usage Notes 


Write Structured Field 


System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


Host Interactive Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the host interaction management portion of the workstation program. 
The function ID is in byte 1, and the error number is in byte 0. Host 
interactive return codes use a function ID of X‘32’. The error codes that 
can be received for this service are: 


Code Meaning 


X‘00’ Successful completion. The message has been sent to and 
acknowledged by the host. 

X‘02’ Invalid service request parameter. 

X‘04’ The session is not connected. 

X‘08’ A system error has occurred. 

X‘0C’ Byte 0 of the parameter list was not zero on request. 

X‘10’ The message you sent was rejected. 


See Appendix H, “Return Codes,” for more information. 


If you specified asynchronous processing, or synchronous processing 
using X‘40’ in both the BH and BL registers on request, you must use 
the Get Request Completion service to obtain the results in the 

parameter list when the Write Structured Fields service is completed. 


Before you use the Write Structured Field service, you must use the 


Define Buffer service to define a buffer to use to receive the next 
transmission of structured field data sent from the host. 


Chapter 7. Coding Host Interactive Service Requests 7-23 


Write Structured Field 


Coding Example 


° 
’ 


; PARAMETER LIST FOR WRITE STRUCTURED FIELD 


WSRETNCD 
WSFXNID 
WSHOSTID 
WSZERO 


WSOFFSD 
WSSEGTD 


WSTASKID 


. 
f 


DB 
DB 
DB 
DB 
DW 
DB 
DB 
DW 
DW 
DW 
DW 
DW 
DW 


0 
0 
0 
0 
0 
Ol 
00 
0 
0 
0 
0 
0 
9 


DUP (0) 


Se et et ee) ee | ee |) eT er TY 


RETURN CODE 

FUNCTION NUMBER 

HOST SESSION ID 

UNCHANGED 

NOT USED 

STRUCTURED FIELD TYPE, (DEST/ORIG) 
UNUSED 

OFFSET ADDRESS OF STRUCTURED FIELD DATA 
SEGMENT ADDRESS OF STRUCTURED FIELD DATA. 
UNUSED 

PC TASK ID 


SYSTEM WORK AREA 


; INITIALIZE PARAMETER LIST FOR WRITE STRUCTURED FIELD 


° 
r 


et er ee Ty 


MOV 
MOV 
MOV 
MOV 


MOV 
MOV 
MOV 
MOV 
MOV 


MOV 
MOV 
MOV 


WSRETNCD , OOH 
WSFXNID,OOH 
AL,HOSTID 

WSHOSTID,AL 


WSOFFSD,OFFSET STRSDA 
WSSEGTD,SEG STRSDATA 


AX,PCTSKID 
WSTASKID , AX 
WSZERO,O 


STRSDATA,0O 


ot i il aT | 


° 
f 
° 
, 
. 
f 


WSRETNCD MUST BE O BEFORE REQUEST 
WSFXNID MUST BE O BEFORE REQUEST 


HOST ID IN 

THE LIST . 
OFFSET AND SEGMENT OF DATA IN LIST 
TA 


PC TASK ID 
IN LIST 
THIS FIELD MUST BE ZEROED 


INITIALIZE THE FIELDS IN THE STRUCTURED FIELD 8 BYTE HEADER. 
STRSDATA IS THE MEMORY LOCATION NAME OF THE BEGINNING OF THE 
STRUCTURED FIELD 8 BYTE HEADER. 


WORD PTR STRSDATA + 4,0 
WORD PTR STRSDATA + 6,0 


; INITIALIZE REGISTERS FOR WRITE STRUCTURED FIELD 


. 
, 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


AH,0O9H 

AL,O4H 

BH, 80H 

BL, 20H 

Cx,0 

DX ,MFIC 

DI, SEG WSRETNCD 
ES ,DI 

DI,OFFSET WSRETNCD 


. 
7 
° 
i 
° 
, 
° 
, 
f 
° 
T 
° 
, 


REPLY IS A COMPLETION SIGNAL 

WAIT FOR A COMPLETION SIGNAL 

PRIORITY IN CX 

RESOLVED VALUE FOR 'MFIC : 

SEGMENT ADDRESS OF PARAMETER LIST 
IN ES 

OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR WRITE STRUCTURED FIELD SERVICE 


° 
t 
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INT 


7AH 


Define Buffer 


Host Interactive Service X‘05’: Define Buffer 


Register Values 


Use this service to define a buffer that will be used to receive a message 
from the specified host session. This service is valid for DFT host sessions 


only. 

On Request On Completion 
AH = X‘09’ AX = Request ID 
AL = X‘05’ CH = X‘12’ 

BH = Synchronous or asynchronous * CL = Return code 
BL = Synchronous or asynchronous * 

CX = X‘0000’ The contents of 

DX = Resolved value for MFIC registers BH, DX, 
ES = Segment address of the parameter list ES, and DI are 

DI = Offset address of the parameter list unpredictable. 


* The values in these registers depend on whether you want the request to be processed 


synchronously or asynchronously. See the following description of request register values 
for more information. 


Request Register Values: 


You can specify synchronous or asynchronous processing of the Define 
Buffer service. In synchronous processing, control is returned to your 
application program after the workstation program has completed the 
request. In asynchronous processing, control is returned to your 
application program before the workstation program has completed the 
request. You must use the Get Request Completion service to obtain 
the parameter list values on completion when you request asynchronous 
processing. 


Synchronous Processing: 
There are two ways to specify synchronous processing: 


1. Set the BH register to X‘80’ and the BL register to X‘20’. When the 
request is completed, control is returned to your application 
program, and the registers and parameter list contain the values for 
completion of the request. . 


2. Set both the BH and BL registers to X‘40’. When the request is 
completed, control is returned to your program, but the parameter 
list values for completion of the request are not obtained until you 
request the Get Request Completion service. 
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Asynchronous Processing: 


For asynchronous processing of the Define Buffer service request, set 
the BH register to X‘40’ and the BL register to X‘00’. When 
asynchronous processing is specified, you must request the Get Request 
Completion service to obtain the results of the Define Buffer service. 


e Completion Register Values: 


If you specified asynchronous processing, or synchronous processing 
using X‘40’ in both the BH and BL registers on request, the AX register 
contains a request ID that the workstation program assigned to the 
request. You use this request ID to match the results of the service 
obtained by the Get Request Completion service to the results of this 
service. That is, when the request ID in the AX register on completion 
of the Get Request Completion service matches the request ID in the AX 
register on completion of this service, the results obtained by the Get 
Request Completion service pertain to this request. 


Parameter List Format 
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a a 
Offset | Length on Request on Completion 

fo [abyte _[Mustibe zero [Retum code ____| 
fo [abyte [xor—SS~*d Unchanged 
fs [1word [Reserved ——~d Reserved 


10 1 word Offset address of Unchanged 
buffer 

12 1 word Segment address of Unchanged 
buffer 


Define Buffer 


Parameter Definitions 
Request Parameters: 


e The session ID is the ID of the host session whose structured field data 
will be received in the buffer being defined. 


e The task ID must be the same task ID that was specified by the 
application program in the parameter list for the Connect to Host 
Session service. 


e The system work area is used by the workstation program while it 
processes the request. This area must be provided in the parameter list. 


e The format of the buffer is as follows: 
4 1 word n (buffer size). This includes the 8-byte 
The maximum buffer size allowed is 3592 
bytes (decimal). 
18s byte | Used for structured field data 
lo 1 byte Used for structured field data 7 
Bytes 0 through 7 are the buffer header. Bytes 8 through n+8 are used 
for the destination/origin structured field message received from the 


prefix. 
6 | Aword _| X‘0000’ 
n+ 8 Used for structured field data 
host. 


e The length of the buffer is the number of bytes in the buffer. The 
maximum buffer size allowed is 3592 (decimal) bytes. 


Return Codes 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


e System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 
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e Host Interactive Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the host interaction management portion of the workstation program. 
The function ID is in byte 1, and the error number is in byte 0. Host 
interactive return codes use a function ID of X‘32’. The error codes that 
can be received for this service are: 


Code Meaning 


X‘00’ Successful completion. 

X‘02’ Invalid service request parameter. 

X‘04’ The session is not connected. 

X‘08’ A system error has occurred. 

X‘0C’ Byte 0 of the parameter list was not zero on request. 


See Appendix H, “Return Codes,” for more information. 


Usage Notes 


e If you specified asynchronous processing, or synchronous processing 
using X‘*40’ in both the BH and BL registers on request, you must use 
the Get Request Completion service to obtain the results in the 
parameter list when the Define Buffer service is completed. 


e You must request the Define Buffer service at the following times: 


— Before the host application that communicates with your 
application is started, so that a message buffer is available in time 
to receive the first message from the host. (To start the host 
application program, your application program can use the 
keyboard services for sending keystrokes to the host.) 


— Before each Write Structured Field service request, so that a 
message buffer is available in time to receive the next message from 
the host session. 

You do not have to use a different message buffer for each Write 

Structured Field service request (although you can if you wish), but you 

must reset the message buffer header as follows: 


1. Set the first two words of the buffer header to zero. 


2. Set the third word of the buffer header to the length of the message 
buffer (including the eight bytes of the buffer header). 


3. Set the fourth word of the message buffer header to zero. 
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Coding Example 


i 
; PARAMETER LIST FOR DEFINE RECEIVE BUFFER 


; 
DBRETNCD DB 


0 ; RETURN CODE 
' DBFXNID DB O ; FUNCTION NUMBER 
DBHOSTID DB 0O ; HOST SESSION ID 
DB O : UNCHANGED 
DW O ; NOT USED 
DB O1 
DB 00 ; UNUSED 
DBOFFSET DW 0 ; SEGMENT AND OFFSET OF THE MESSAGE BUFFER 
DBSEGMNT DW 0 
DW O ; UNUSED 
DBTASKID DW 0 ; PC TASK ID 
DW O 
DW 9 DUP(0O) ; SYSTEM WORK AREA 


INITIALIZE PARAMETER LIST FOR DEFINE RECEIVE BUFFER 


~e Ne we 


MOV DBRETNCD, OOH 
MOV DBFXNID, OOH 


DBRETNCD MUST BE O BEFORE REQUEST 
DBFXNID MUST BE O BEFORE REQUEST 


MOV AL, HOSTID HOST ID IN 
MOV DBHOSTID,AL THE LIST 
MOV AX, PCTSKID PC TASK ID 


IN THE LIST 

OFFSET OF MESSAGE BUFFER 
IN THE LIST 

SEGMENT OF THE MESSAGE BUFFER 
IN THE LIST 


MOV DBTASKID,AX 

MOV AX,OFFSET BUFFER 
MOV DBOFFSET,AX 

MOV AX,SEG BUFFER 
MOV DBSEGMNT,AX 


ST i a a Se Ei i el ei al | 


INITIALIZE THE 8 BYTE HEADER OF THE MESSAGE BUFFER. 
BUFFER IS THE MEMORY LOCATION NAME OF THE BEGINNING OF THE 
STRUCTURED FIELD 8 BYTE HEADER. 


~“e Se Ne Oe Ne 


MOV BUFFER ,O 
MOV WORD PTR BUFFER + 2,0 
MOV WORD PTR BUFFER + 6,0 


INITIALIZE REGISTERS FOR DEFINE RECEIVE BUFFER 


~e Me Ne 


MOV AH,0O9H 
MOV AL,O5H 
MOV BH,40H 
MOV BL,40H 


REPLY 
WAIT TYPE IN BL 


MOV CX ,0 PRIORITY IN CX 
MOV DI, SEG DBRETNCD SEGMENT ADDRESS OF PARAMETER LIST 
MOV ES ,DI IN ES 


MOV DX ,MFIC ; RESOLVED VALUE FOR 'MFIC : 


MOV DI,OFFSET DBRETNCD OFFSET OF PARAMETER LIST IN DI 


SIGNAL WORKSTATION PROGRAM FOR DEFINE RECEIVE BUFFER SERVICE 


“=e “we se 


INT 7AH 
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Introduction 


Requesting the Presentation Space Services 

Return Codes for the Presentation Space Services 
Presentation Space Service X‘01’: 
Presentation Space Service X‘02’: 
Presentation Space Service X‘03’: 
Presentation Space Service X‘04’: 
Presentation Space Service X‘05’: 
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Introduction 


Introduction 


This chapter describes how to code requests for the presentation space 
services provided by the API. 


The presentation space services allow your application program to create 
and delete personal computer presentation spaces, to display them, and to 
control the position of the cursor in them. 


The presentation space services provided by the API are: 


e Define Presentation Space Service: Use this service to define a 
presentation space, and to obtain the session ID that the workstation 
program assigns to that presentation space. 


e Delete Presentation Space Service: Use this service to delete a 
presentation space created by the Define Presentation Space service. 
Any window created on this presentation space is also deleted. 


e Display Presentation Space Service: Use this service to display 
any changes made in the specified presentation space. 


e Set Cursor Service: Use this service to set a cursor position in a 
presentation space. 


e Switch Presentation Space Service: Use this service to specify a 
presentation space as the default presentation space for all DOS and 
BIOS updates. 


Requesting the Presentation Space Services 


To request any of the presentation space services, load the registers and the 
parameter list with the proper values, and use the INT 7AH instruction to 
signal the workstation program that it has a request to process. 


Note: Before your application can request the presentation space services, it 
must request the Name Resolution service, using ‘PCPSM  ’ as the 
gate name in the parameter list. (Remember that the gate name must 
be padded to the right with blanks if it is less than eight characters.) 


Return Codes for the Presentation Space Services 


Each presentation space service has two return codes associated with it: a 
system return code and a presentation space management return code. 
Both types of return codes are 2-byte values made up of a function ID and 
an error number. The function ID indicates the portion of the workstation 
program in which the error occurred. The error number indicates the 
specific type of error that has occurred. An error number of X‘00’ always 
indicates a successful acceptance or completion of the request. 


Introduction 


e System Return Codes: 


After your application has requested a presentation space service, the 
CH and CL registers contain a return code generated by the request 
processing portion of the workstation program. The function ID is in 
the CH register, and the error number is in the CL register. System 
return codes use a function ID of X‘12’. The error codes that can 
appear are: 


Code Meaning 


X‘00’ Request accepted. 

X‘05’ Invalid index specified. 
X‘07’ Invalid reply specified. 
X‘08’ Invalid wait type specified. 
X‘0B’ RQE pool depleted. 

X‘OF’ Invalid environment access. 
X‘34’ Invalid gate entry. 


These system return codes apply to all presentation space services. 
e Presentation Space Services Return Codes: 


After a requested presentation space service is completed, bytes 0 and 1 
of the parameter list contain a return code generated by the 
presentation space management portion of the workstation program. 
The function ID is in byte 1, and the error number is in byte 0. 
Presentation space return codes use a function ID of X‘69’. The error 
numbers that can appear are specific to the service that was requested 
and are included in the descriptions of each service. 


See Appendix H, “Return Codes,” for more information. 
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Presentation Space Service X‘01’: Define Presentation 


Space 


Register Values 
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Use this service to define a presentation space and to obtain the session ID 
that the workstation program assigns to it. This service is allowed only if 
Multi-DOS is selected at customization time. 


On Request On Completion 

AH = X‘09’ CH = X‘12’ 

AL = X‘ Ol’ CL = Return code 
BH = X‘80’ 

BL = X‘20’ The contents of 

CX = X‘O0FF’ registers AX, BX, DX, 
DX = Resolved value for PCPSM ES, and DI are 

ES = Segment address of the parameter list unpredictable. 

DI = Offset address of the parameter list 


Function 1D O60) 
2 


4 1 word Offset address of the Unchanged 
presentation space 
work area 
1 word Segment address of Unchanged 
the presentation space 
work area 
1 word Offset address of the Unchanged 
presentation space 
data stream 
10 1 word Segment address of Unchanged 
the presentation space 
data stream 


byte Unchanged 
1 byte Window short name 


fo byte 


Define Presentation Space 


Parameter Definitions 


Request Parameters: 


The presentation space work area is a 1552-byte area that your 
application program must provide. 


The presentation space data stream is in the following format: 


— Header 
— Elements in the form of command data 


The header is a 1-byte value that contains the number of commands you 
have coded in the data stream. 


Each command is specified as a 1-byte value indicating the command 
number, followed by a variable-length amount of data. 


Commands 01, 02, and 03 are required to define a presentation space, 
while 05 and 06 are optional. Command 07 is used only for a specific 
function—3270 keystroke emulation. 


The commands available in the presentation space data stream, and 
their data format, are as follows: 


~ Command 01: Set Presentation Space Size 


The only presentation space currently supported is 25 rows by 80 
columns. (The presentation space is the buffer described for 
command 03.) The data format is one byte containing X‘19’, which 
indicates 25 rows in hexadecimal followed by one byte containing 
X‘50’, which indicates 80 columns in hexadecimal. 


— Command 02: Set Presentation Space Type 


The data format is one byte containing X‘00’, which indicates text 
indirect. The application program uses either a presentation space 
or the BIOS or DOS calls that must be routed to a presentation 
space. 


— Command 03: Set Presentation Space Buffer 


The data format is one word containing the offset address of the 
presentation space buffer, followed by one word containing the 
segment address of the presentation space buffer. 


The size of the presentation space buffer must be twice the number 
of character positions in the presentation space. (Hach character 
needs two bytes of information for it to be displayed.) Thus, for a 
presentation space of 25 rows with 80 columns each, the 
presentation space size must be 4000 bytes. (See Command 01.) 


The space for the presentation space buffer must be provided by 
your application program. 
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— Command 04: Reserved 
— Command 05: Set Window Long Name 


The data format is eight bytes containing the window long name. 
The window long name can be as many as eight ASCII characters 
long, and it must begin with an alphabetic character. If the window 
long name is less than eight characters long, it must be padded to 
the right with blanks. This command is optional. 


— Command 06: Set Window Short Name 


The data format is one byte containing the window short name. 

This command is optional. If the window short name is not 
specified, the workstation program assigns the first unused letter 
from A through Z as the window short name. If a short name is 
supplied, it must be a unique short name (one not already in use). If 
the short name supplied is currently in use, the Define Presentation 
Space request will not be completed successfully. 


~ Command 07: Set Session Attribute Buffer 


The data format is one word containing the offset address of the 
session attribute buffer, followed by one word containing the 
segment address of the session attribute buffer. The size of the 
session attribute buffer must be twice the number of rows specified 
in command 01 of the presentation space data stream. 


This buffer is an internal work space allocated in the user area; it 
should not be altered by the user. The workstation program uses 
this buffer for 3270 attribute algorithms. 


This command should be used only if you intend to use 3270 
keystroke emulation in this presentation space. For more 
information, refer to Chapter 9, “Coding 3270 Keystroke Emulation 
Service Requests.” 


Completion Parameters: 


The session ID is the ID identifying this presentation space. Use this 
session ID for all further communication with this presentation space or 
its window. 


The window short name is the 1-character ASCII name of the window 
associated with the presentation space. This window short name is 
either provided in the presentation space data stream (command 06) or 
provided by the workstation program. If it is provided by the 
workstation program, it will be the first letter from A through Z that is 
not currently used as a short window name. 


Return Codes 


Define Presentation Space 


e System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


e You may receive return codes from the session information services, 
with a function code of X‘6B’. 


e Presentation Space Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the presentation space management portion of the workstation program. 
The function ID is in byte 1, and the error number is in byte 0. 
Presentation space return codes use a function ID of X‘69’. The error 
codes that can be received for this service are: 


Code 


X‘00’ 
X‘0A’ 


X‘0B’ 


X‘0C’ 
X‘0D’ 


X‘OF’ 
X11’ 


X‘13’ 
X‘14’ 


X‘15’ 


X‘18’ 


X*19’ 


Meaning 


Successful completion. 

An invalid number of commands is in the presentation space 
data stream. 

An invalid number of rows/columns is in the presentation 
space data stream. 

Byte 0 of the parameter list was not zero on request. 

There is invalid data in the Set Presentation Space Type data 
stream command. 

A command that had no data was found in the presentation 
space data stream. 

Invalid parameter. 

The address of the work area was zero on request. 

The maximum number of personal computer presentation 
spaces has already been created, or DOS has been configured 
and you attempt to create an alternate presentation space 
(ALT PS). 

The Set Presentation Space Buffer command was missing 
from the presentation space data stream. 

The Set Presentation Space Size command was missing from 
the presentation space data stream. 

The Set Presentation Space Type command was missing from 
the presentation space data stream. 


See Appendix H, “Return Codes,” for more information. 
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Usage Notes 
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A window for the presentation space is created on screen profile 0 and 
also on the current screen. You can use the presentation space data 
stream to specify the window short and long names. If no short name is 
specified, a default short name is provided. The workstation program 
assigns the first unused character from A through Z as the default 
window short name. There is no default for the long name. 


The only type of presentation space that can be created is a personal 
computer presentation space. 


The presentation space that was the default remains the default for all 
DOS and BIOS updates until the switch occurs for the new presentation 
space just defined by the application program. After the switch occurs, 
the new presentation space becomes the default. To specify another 
presentation space as the default for DOS and BIOS updates, use the 
Switch Presentation Space service. 


Before exiting, your application program should use the Delete 
Presentation Space service to delete any presentation spaces it may 
have created with this service. 


For each presentation space that you create using this service, you 
must provide a unique 1552-byte work area. 


A session defined by your application program as a result of a Define 
Presentation Space service request requires that a Connect to Keyboard 
service request with an All key intercept option be issued in order to 
receive and process keystrokes. A second Connect to Keyboard service 
request can be issued relative to a Define Presentation Space session. 


Define Presentation Space 


Coding Example 


e 
ra 


; PRESENTATION SPACE DATA STREAM FOR DEFINE PRESENTATION SPACE 


PSDS DB 5 ; PSDS HEADER - 5 COMMANDS 
SETSIZE DB O1H COMMAND TO SET THE PS SIZE 


PSROWS DB 25 25 ROWS IN THE PS 

PSCOLS DB 80 80 COLUMNS IN THE PS 

SETTYPE DB -Q2H COMMAND TO SET THE PS TYPE 
DB OOH TYPE = TEXT INDIRECT 


COMMAND TO SET THE PS BUFFER 

PS OFFSET 

PS SEGMENT 

COMMAND TO SET THE WINDOW LONG NAME 
WINDOW LONG NAME 

COMMAND TO SET WINDOW SHORT NAME 
WINDOW SHORT NAME 


SETPSBUF DB 03H 
PSOFFSET DW 0 
PSSEGMNT DW 0 
SETLNGNM DB 05H 
LONGNAME DB 'SAMPLE ' 
SETSHTNM DB O6H 
SHRTNAME DB 'X'! 


; PARAMETER LIST FOR DEFINE PRESENTATION SPACE 


Sl al a el i el eal Sal a et et eT eT 


DPRETNCD DB 


RETURN CODE 
DPFXNID DB FUNCTION NUMBER 
DPSESSID DB SESSION ID 
DPRESERV DB RESERVED 


DPBUFOFF DW 
DPBUFSEG DW 
DPDSOFF DW 
DPDSSEG DW 

DB 
DPWINDOW DB 


OFFSET OF DATA STREAM 
SEGMENT OF DATA STREAM 
MUST BE O 

RETURNED WINDOW SHORT NAME 


TT at Mt a Sy a! ST a eT 


Ooooooo0co000 


NEW PRESENTATION SPACE 


‘S) DB 4000 DUP(0) 


FU we we we 


KEYSTROKING BUFFER 


KSBUF DB 128 DUP(0O) 


1552 BYTE WORK AREA 


WORKAREA DB~ 1552 DUP(0) 


; INITIALIZE PRESENTATION SPACE DATA STREAM FOR DEFINE PRESENTATION SPACE 
i 

MOV PSOFFSET,OFFSET PS ; OFFSET OF PS INTO THE PSDS 

MOV PSSEGMNT,SEG PS ; SEGMENT OF PS INTO THE PSDS 


Chapter 8. Coding Presentation Space Service Requests 


OFFSET ADDRESS OF THE 1552 BYTE WORK AREA 
SEGMENT ADDRESS OF THE 1552 BYTE WORK AREA 
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° 
7 


. 
f 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


° 
, 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


° 
Y 


DPRETNCD, 00H ; 
DPFXNID,OOH ; 
AX,OFFSET WORKAREA ; 
DPBUFOFF, AX 
AX,SEG WORKAREA ; 
DPBUFSEG , AX 
AX,OFFSET PSDS ; 
DPDSOFF , AX 
AX,SEG PSDS ; 
DPDSSEG , AX 


AH, 09H 
AL,O1H 

BH, 80H 

BL, 20H 

CX, OFFH 

DX,PCPSM : 
DI, SEG DPRETNCD ; 
ES,DI ; 
DI,OFFSET DPRETNCD ; 


INITIALIZE PARAMETER LIST FOR DEFINE PRESENTATION SPACE 


RETURN CODE MUST O BEFORE REQUEST 
FUNCTION ID MUST O BEFORE REQUEST 
WORK AREA OFFSET INTO THE LIST 


WORK AREA SEGMENT INTO THE LIST 
PSDS OFFSET INTO THE LIST 


PSDS SEGMENT INTO THE LIST 


; INITIALIZE REGISTERS FOR DEFINE PRESENTATION SPACE 


RESOLVED VALUE FOR 'PCPSM ' 

SEGMENT ADDRESS OF PARAMETER LIST 
IN ES 

OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR DEFINE PRESENTATION SPACE SERVICE 


. 
i 


INT 
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Delete Presentation Space 


Presentation Space Service X‘02’: Delete Presentation 
Space 


Use this service to delete a presentation space created by the Define 
Presentation Space service. This service is allowed only if Multi-DOS is 


selected at customization time. Any window created on this presentation 
space is also deleted. 


Register Values 


On Request On Completion 

AH = X‘09’ CH = X‘12’ 

AL = X‘02’ CL = Return code 
BH = X‘80’ 

BL = X‘20’ The contents of 

CX = X‘OOFF’ registers AX, BX, DX, 
DX = Resolved value for PCPSM ES, and DI are 

ES = Segment address of the parameter list unpredictable. 

DI = Offset address of the parameter list 


Offset | Length on Request on Completion 
fo | ibyte [Must be zero | Return code 


Parameter Definitions 
Request Parameters: 


e The session ID is the ID that was assigned to the presentation space by 
the Define Presentation Space service. 
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Return Codes 
e System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. . 


e Presentation Space Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the presentation space management portion of the workstation program. 
The function ID is in byte 1, and the error number is in byte 0. : 
Presentation space return codes use a function ID of X‘69’. The error 
codes that can be received for this service are: 


Code Meaning 


X‘00° Successful completion. 

X‘02’ Invalid session ID. 

X‘0C’ Byte 0 of the parameter list was not zero on request. 
X‘10’ The specified presentation space cannot be deleted. 


See Appendix H, “Return Codes,” for more information. 


Usage Notes 


e Any window created on this presentation space is deleted from all 
screen profiles on which it appears, as well as from screen profile 0. 
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Coding Example 


; PARAMETER LIST FOR DELETE PRESENTATION SPACE 
DYRETNCD DB 
DYFXNID DB 
DYSESSID DB 
DYRESERV DB 


RETURN CODE 
FUNCTION NUMBER 
SESSION ID 
RESERVED 


oO0o00 


° 
’ 


; INITIALIZE PARAMETER LIST FOR DELETE PRESENTATION SPACE 


MOV DYRETNCD , OOH ; RETURN CODE MUST = O BEFORE REQUEST 
MOV DYFXNID, OOH ; FUNCTION ID MUST = O BEFORE REQUEST 
MOV AL,SESSID ; HANDLE ID INTO THE LIST 


MOV DYSESSID,AL 
; INITIALIZE REGISTERS FOR DELETE PRESENTATION SPACE 


MOV AH,O9H 
MOV AL,02H 
MOV BH, 80H 
MOV BL,20H 
MOV CX,OFFH 
MOV DX,PCPSM ; RESOLVED VALUE FOR 'PCPSM  ' 
MOV DI, SEG DYRETNCD ; SEGMENT ADDRESS OF PARAMETER LIST 
MOV ES,DI ; IN ES 
MOV ODI,OFFSET DYRETNCD ; OFFSET OF PARAMETER LIST IN DI 
; SIGNAL WORKSTATION PROGRAM FOR DELETE PRESENTATION SPACE SERVICE 


INT 7AH 
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Presentation Space Service X‘03’: Display Presentation 
Space 


Use this service to display any changes made in the specified presentation 


space. 
Register Values 
On Request | On Completion 
AH = X‘09’ CH = X‘12’ 
AL = X‘03’ CL = Return code 
BH = X‘80’ 
BL = X‘20’ The contents of 
CX = X‘O0OFF’ registers AX, BX, DX, 
DX = Resolved value for PCPSM ES, and DI are 
ES = Segment address of the parameter list unpredictable. 
DI = Offset address of the parameter list 


Parameter Definitions 


Request Parameters: 


e The session ID is the ID that was assigned to the presentation space by 
the Define Presentation Space service. 


e The starting offset is a character offset into the presentation space 
buffer, specifying the first character to display. 


e The length is the number of characters to be displayed. 
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Return Codes 
e System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


e Presentation Space Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the presentation space management portion of the workstation program. 
The function ID is in byte 1, and the error number is in byte 0. 
Presentation space return codes use a function ID of X‘69’. The error 
codes that can be received for this service are: 


Code Meaning 


X‘00’ Successful completion. 

X‘02’ Invalid session ID. 

X‘03’ The specified offset for display is not within the address of 
the presentation space. 

X‘09’ The specified length is invalid. 

X‘0C’ Byte 0 of the parameter list was not zero on request. 

X‘11’ Invalid parameter. 


See Appendix H, “Return Codes,” for more information. 
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Coding Example 
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. 
f 


; PARAMETER LIST FOR DISPLAY PRESENTATION SPACE 


RDRETNCD 
RDFXNID 

RDSESSID 
RDRESERV 
RDCHROFF 
RDLENGTH 


DB 
DB 
DB 
DB 
DW 
DW 


ooo0o00 


RETURN CODE 

FUNCTION NUMBER 

SESSION ID 

RESERVED 

STARTING CHARACTER OFFSET 
NUMBER OF CHARACTERS TO DISPLAY 


Pe eT eT aT eT | 


; INITIALIZE PARAMETER LIST FOR DISPLAY PRESENTATION SPACE 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


RDRETNCD, OOH 
RDFXNID, OOH 
AL,SESSID 
RDSESSID,AL 
RDCHROFF ,0 
RDLENGTH , 2000 


; INITIALIZE REGISTERS FOR DISPLAY 


. 
t 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


AH,O9H 

AL,03H 

BH, 80H 

BL,20H 

CX, OF FH 

DX,PCPSM 

DI, SEG RDRETNCD 
ES,DI 

DI,OFFSET RDRETNCD 


; RETURN CODE MUST = O BEFORE REQUEST 
; FUNCTION ID MUST = 0 BEFORE REQUEST 
; SESSION ID INTO THE 


PARAMETER LIST 
START AT THE 1ST CHARACTER 
DISPLAY 2000 CHARACTERS 


PRESENTATION SPACE 


RESOLVED VALUE FOR 'PCPSM . 
SEGMENT ADDRESS OF PARAMETER LIST 
IN ES 

OFFSET OF PARAMETER LIST IN DI 


=e Ne NO Me 


; SIGNAL WORKSTATION PROGRAM FOR DISPLAY PRESENTATION SPACE SERVICE 


° 
f 


INT 


7AH 


Set Cursor Position 


Presentation Space Service X‘04’: Set Cursor Position 


Use this service to set a cursor position in a presentation space. 


Register Values 


On Request On Completion 

AH = X‘09’ CH = X‘12’ 

AL = X‘04’ CL = Return code 
BH = X‘80’ 

BL = X‘20’ The contents of 

CX = X‘OOFF’ registers AX, BX, DX, 
DX = Resolved value for PCPSM ES, and DI are 

ES = Segment address of the parameter list unpredictable. 

DI = Offset address of the parameter list 


Parameter List Format 


Contents Contents 
Offset | Length on Request on Completion 
iets 


Function ID (X'69) 
Unchanged 


1 
2 
3 


Unchanged 
1 byte Cursor type Unchanged 


aa 
ee 
a 
[3 |ibyte | Reserved [Reserved 
a 
ie 


Parameter Definitions 
Request Parameters: 


e The session ID is the ID that was assigned to the presentation space by 
the Define Presentation Space service. 


e The cursor address is an offset into the presentation space buffer, 
specifying character position to set the cursor. 
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Set Cursor Position 


Return Codes 
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The character position for the cursor is derived from the following 
formula: 


[Row number x number of columns] + column number 


where: 


“Row number” is the number of the row that you want the cursor to 
be positioned in (0 to 24). 


“Number of columns” is the number of columns defined in the 
presentation space. 


“Column number” is the number of the column that you want the 
cursor to be positioned in (0 to 79). 


The cursor type byte is as follows (where bit 0 is the high-order bit and 
bit 7 is the low-order bit): 


AIO of WN = © 


Reserved 

Reserved 

Reserved 

Inhibited cursor with autoscroll 
Reserved 

Inhibited cursor 

Blinking cursor 

Box cursor 


A blinking underscore cursor appears as 

A blinking box cursor appears as 

An inhibited cursor is not displayed. When the cursor position 

changes, the text in the window is not moved to keep the cursor 
inside the window borders. 

An inhibited cursor with autoscroll is not displayed. When the 


cursor position changes, the text in the window is moved to keep 
the cursor inside the window borders. 


System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


Set Cursor Position 


e Presentation Space Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the presentation space management portion of the workstation program. 
The function ID is in byte 1, and the error number is in byte 0. 
Presentation space return codes use a function ID of X‘69’. The error 
codes that can be received for this service are: 


Code . Meaning 
X‘00’ Successful completion. 


X‘02’ Invalid session ID. 
X‘06’ Invalid cursor type. 


X‘07’ Invalid cursor address. 
X‘0C’ Byte 0 of the parameter list was not zero on request. 
X‘11’ Invalid parameter. 


See Appendix H, “Return Codes,” for more information. 


Usage Notes 


e Request this service each time you wish to change the position of the 
cursor. 


e The cursor only appears in the active window, data autoscrolls if 
necessary to keep the cursor in view, and the cursor always blinks. 
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Set Cursor Position 


Coding Example 
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e 
a 


; PARAMETER LIST FOR SET CURSOR POSITION 


DCRETNCD 
DCFXNID 

DCSESSID 
DCRESRV1 
DCCURADD 
DCCURTYP 
DCRESRV2 


e 
I 


DB 
DB 
DB 
DB 
DW 
DB 
DB 


OoOOO0O000 


se Ne Se Ne Ne Me NO 


RETURN CODE 
FUNCTION NUMBER 
SESSION ID 
RESERVED 

CURSOR ADDRESS 
CURSOR TYPE 
RESERVED 


; INITIALIZE PARAMETER LIST FOR SET CURSOR POSITION 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


DCRETNCD , OOH 
DCFXNID, OOH 
AL,SESSID 
DCSESSID,AL 
DCCURADD ,0 
DCCURTYP ,O1H 


St Bt et Be 


RETURN CODE MUST 
FUNCTION ID MUST 
SESSION ID INTO THE 

PARAMETER LIST 

DISPLAY CURSOR AT THE HOME POSITION 
CURSOR TYPE = BOX CURSOR 


0 BEFORE REQUEST 
0 BEFORE REQUEST 


; INITIALIZE REGISTERS FOR SET CURSOR POSITION 


. 
t 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


AH, 09H 

AL,04H 

BH, 80H 

BL, 20H 

CX, OFFH 

DX ,PCPSM 

DI, SEG DCRETNCD 
ES ,DI 

DI,OFFSET DCRETNCD 


e 
? 
° 
e 
. 
f 
° 
‘ 


+; SIGNAL WORKSTATION PROGRAM FOR SET 


° 
, 


INT 


7AH 


RESOLVED VALUE FOR 'PCPSM : 
SEGMENT ADDRESS OF PARAMETER LIST 
IN ES 

OFFSET OF PARAMETER LIST IN DI 


CURSOR POSITION SERVICE 


Switch Presentation Space 


Presentation Space Service X‘05’: Switch Presentation 
Space 


Use this service to specify a presentation space to become the default 
presentation space for all DOS and BIOS updates. 


Register Values 


On Request On Completion 

AH = X‘09’ CH = X‘12’ 

AL = X‘08’ CL = Return code 
BH = X‘80’ 

BL = X‘20’ The contents of 

CX = X‘O0OFF’ registers AX, BX, DX, 
DX = Resolved value for PCPSM ES, and DI are 

ES = Segment address of the parameter list unpredictable. 

DI = Offset address of the parameter list 


Offset | Length on Request on Completion 
|0 | ibyte | Mustbezero | Return code 


Parameter Definitions 
Request Parameters: 


e The session ID is the ID that was assigned to the presentation space by 
the Define Presentation Space service. 


Return Codes 
e System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 
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Switch Presentation Space 


e Presentation Space Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the presentation space management portion of the workstation program. 
The function ID is in byte 1, and the error number is in byte 0. 
Presentation space return codes use a function ID of X‘69’. The error 
codes that can be received for this service are: 


Code Meaning 


X‘00’ Successful completion. 
X‘02’ Invalid session ID. 
X‘0C’ Byte 0 of the parameter list was not zero on request. 


See Appendix H, “Return Codes,” for more information. 


Coding Example 


. 
f 


; PARAMETER LIST FOR SWITCH PRESENTATION SPACE 


SPRETNCD DB 
SPFXNID DB 
SPSESSID DB 
SPRESERV DB 


RETURN CODE 
FUNCTION NUMBER 
SESSION ID 
RESERVED 


oO0o00 


se Ne NO ON 


; INITIALIZE PARAMETER LIST FOR SWITCH PRESENTATION SPACE 


MOV SPRETNCD , OOH ; RETURN CODE MUST = O BEFORE REQUEST 
MOV SPFXNID, 00H ; FUNCTION ID MUST = O BEFORE REQUEST 
MOV AL, SESSID ; SESSION ID INTO THE LIST 


MOV SPSESSID,AL 
; INITIALIZE REGISTERS FOR SWITCH PRESENTATION SPACE 


MOV AH,09H 
MOV AL,O5H 
MOV BH, 80H 
MOV BL,20H 
MOV CX,OFFH 
MOV DX,PCPSM | ; RESOLVED VALUE FOR 'PCPSM ' 
MOV DI, SEG SPRETNCD ; SEGMENT ADDRESS OF PARAMETER LIST 
MOV ES,DI ; IN ES 
MOV DI,OFFSET SPRETNCD ; OFFSET OF PARAMETER LIST IN DI 
; SIGNAL WORKSTATION PROGRAM FOR SWITCH PRESENTATION SPACE SERVICE 


INT 7AH 
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Switch Presentation Space 
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Introduction 


Introduction 


This chapter describes how to code requests for the 3270 keystroke 
emulation services provided by the API. This service is allowed only if 
Multi-DOS is selected at customization time. 


The 3270 keystroke emulation services enable you to type into a personal 
computer presentation space as if it were a host presentation space. 
Keystrokes that previously were valid only for host sessions are processed 
by the 3270 keystroke emulation task for personal computer sessions as 
well. 


The 3270 keystroke emulation services are activated in your personal 
computer session by issuing the INDEML command. To use the 3270 
keystroke services, your application must first issue a Define Presentation 
Space command to define a presentation space. This presentation space 
should have no more than 24 rows or 80 columns. Screen row 25 is reserved 
for the operator information area (OIA). You must run the INDEML utility 
in each PC session for which you want to use 3270 Keystroke Emulation. 
See Chapter 10 in the IBM 3270 Workstation Program User’s Guide and 
Reference for more information. 


The format of a personal computer session defined to accept 3270 keystroke 
emulation is the same as the format of a standard personal computer 
session. However, the contents of that presentation space are interpreted 
and processed differently from other personal computer presentation spaces. 
A presentation space defined to accept 3270 keystroke emulation is 
interpreted as having 3270 field attributes as well as personal computer 
ASCII characters. 


Field Attribute Definition for 3270 Keystroke Emulation 


9-2 


Field attributes are contained in two bytes and are defined as any personal 
computer ASCII character with a hexadecimal value between X‘CO’ and 
X‘FF’, and a character attribute of nondisplay (X‘00’). This enables all 256 
characters of the personal computer character set to be displayed with 3270 
keystroke emulation. Field attributes occupy character positions within 
the presentation space. The first byte within a field is a field attribute 
character that defines the characteristics of the field. A field continues 
until the next field attribute is encountered in the presentation space. 
Fields within the presentation space can wrap from the bottom of the 
presentation space to the top of the presentation space. The 3270 keystroke 
emulation task interprets field attributes within the presentation space and 
applies the 3270 keystroke rule defined by the field attribute to all 
keystrokes entered into the presentation space field. The following table 
describes the field attribute character bit assignment. (Remember that bit 0 
is the high-order, leftmost, bit in the byte, and bit 7 is the low-order, 
rightmost, bit in the byte.) 


Note: Only the 3270 base attributes are supported. 


Introduction 


EBCDIC 
Bit Field Characteristics 


11 = This byte is an attribute 


0 
1 


= Unprotected 

= Protected (see Note) 

0 = Alphanumeric . 

1 = Numeric (if numeric lock capability is activated, causes 
automatic numeric shift of keyboard) (see Note) 


00 
01 
10 
11 


Display not detectable by Cursor Select key 
Display detectable by Cursor Select key 
Intensified display detectable by Cursor Select key 
Nondisplay, nonprint, nondetectable 


Reserved: always 0 


Modified data tag (MDT); identifying modified fields during 
Read Modified command operation 


0 = Field has not been modified 
1 = Field has been modified by the operator. Can also be 
set by a program in the presentation space. 


Note: Binary 11 in bits 2 and 3 causes an automatic skip. 


When a personal computer presentation space defined to accept 3270 
keystroke emulation is defined or redisplayed using presentation space 
services, all character attributes in the presentation space are set to display 
the character in the color defined by that character’s field attribute. 
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Presentation Space Format for 3270 Keystroke Emulation 


When defined to accept 3270 keystroke emulation, the presentation space is 


9-4 


vase [ow Pe [om [oe [ sw Pom [oe Pou [oe 


Attribute 
Character 


interpreted as follows: 


ve a ec 


Character Attribute 

Set by PC/PSM on White — Intensified/protected 
Create and Display Blue — Normal/protected 
Spice senianen Red — Intensified/unprotected 


Green — Normal/unprotected 


The 3270 keystroke emulation services provided by the API are: 


e Connect for 3270 Keystroke Emulation Service: Use this service 
to connect the 3270 keystroke emulation task to the session identified in 
the request. 


e Disconnect for 3270 Keystroke Emulation Service: Use this 
service to disconnect the 3270 keystroke emulation task from the 
session identified in the request. 


e Read AID Key Service: Use this service to enable operator input at 
the keyboard until a valid AID key is entered. The 3270 PC READ AID 
API allows you to choose how the application will receive AID keys. 
You can receive each AID key as a scan code/shift state or as a 2- or 
4-byte ASCII mnemonic. Select the ASCII option by setting the 
high-order bit of byte 3 in the parameter list during READ API request. 
The ASCII mnemonic is returned in bytes 10-18 of the parameter list. 


Your personal computer application program formats the presentation 
space by storing characters and field attributes directly in the presentation 
space buffer. After formatting the presentation space, use the Display 
Presentation Space and Display Cursor services to display the formatted 
presentation space. 


Introduction 


After the presentation space has been formatted and displayed, request the 
Read AID Key service to enable operator input from the keyboard. When 
the Read AID Key service request is completed, your application program 
must interrogate the contents of the presentation space, or scan the field 
attributes for attributes with the modified data tag (MDT) bit set, to 
determine which fields have been modified. Your application should modify 
and, if necessary, redisplay the presentation space before the next Read AID 
Key service request. 


Requesting the 3270 Keystroke Emulation Services 


To request any of the 3270 keystroke emulation services, load the registers 
and the parameter list with the proper values, and use the INT 7AH 
instruction to signal the workstation program that it has a request to 
process. 


Note: Before your application can request the 3270 keystroke emulation 
services, it must request the Name Resolution service, using 
‘8270EML ’ as the gate name in the parameter list. (Remember that 
the gate name must be padded to the right with blanks if it is less 
than eight characters.) 


Return Codes for the 3270 Keystroke Emulation Services 


Each 3270 keystroke emulation service has two return codes associated 
with it: a system return code and a 3270 keystroke emulation services 
return code. Both types of return codes are 2-byte values made up of a 
function ID and an error number. The function ID indicates the portion of 
the workstation program in which the error occurred. The error number 
indicates the specific type of error that has occurred. An error number of 
X‘00’ always indicates a successful acceptance or completion of the request. 


e System Return Codes: 


After your application has requested a 3270 keystroke emulation 
service, the CH and CL registers contain a return code generated by the 
request processing portion of the workstation program. The function ID 
is in the CH register, and the error number is in the CL register. 
System return codes use a function ID of X‘12’. The error codes that 
can appear are: 


Code Meaning 


X ‘00’ Request accepted. 

X‘05’ Invalid index specified. 
X‘07’ Invalid reply specified. 
X‘08’ Invalid wait type specified. 
X‘0B’ RQE pool depleted. 

X‘OF’ Invalid environment access. 
X ‘34’ Invalid gate entry. 
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These system return codes apply to all 3270 keystroke emulation 
services. 


@ 3270 Keystroke Emulation Services Return Codes: 


After a requested 3270 keystroke emulation service is completed, bytes 0 
and 1 of the parameter list contain a return code generated by the 3270 
keystroke emulation management portion of the workstation program. 
The function ID is in byte 1, and the error number is in byte 0. The 
3270 keystroke emulation services return codes use a function ID of 
X‘6E’. The error numbers that can appear are specific to the service 
that was requested and are included in the descriptions of each service. 


See Appendix H, “Return Codes,” for more information. 


Connect for 3270 Keystroke Emulation 


3270 Keystroke Emulation Service X‘01’: Connect for 3270 


Keystroke Emulation 


Use this service to attach a 3270 keystroke emulation task to your PC 
presentation space that has been defined to accept 3270 keystroke 
emulation. On successful completion of this service, operator input to the 
keyboard of the connected session is disabled, so that the operator cannot 


type keystrokes to that session from the keyboard. 


Register Values 


Segment address of the parameter list 
Offset address of the parameter list 


On Request 

AH = X‘09’ 

AL = X‘0OL’ 

BH = X‘80’ 

BL = X‘20’ 

CX = X‘O0OFF’ 

DX = Resolved value for 3270EML 


On Completion 


BL = Return type 
CH = X‘12’ 
CL = Return code 


The contents of 
registers AX, BH, DX, 
ES, and DI are 
unpredictable. 


Work area offset 


Unchanged 
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Connect for 3270 Keystroke Emulation 


Parameter Definitions 


Return Codes 
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Request Parameters: 


The session ID is the ID of the PC presentation space returned on the 
Define Presentation Space request. The PC presentation space must be 
defined to accept 3270 keystroke emulation. 


The work area is a 700-byte area of working storage that your 
application program must provide. The work area is allocated to the 
keystroke emulation task until the Disconnect 3270 Keystroke 
Emulation service request is issued. 


Completion Parameters: 


The keystroke task ID is the task ID of the 3270 keystroke emulation 
task. This task ID is required on both the Read AID Key service and the 
Disconnect 3270 Keystroke Emulation service request. This is the task 
provided by the workstation program that performs the 3270 keystroke 
emulation for the specified presentation space. 


System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


3270 Keystroke Emulation Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the 3270 keystroke emulation management portion of the workstation 
program. The function ID is in byte 1, and the error number is in byte 
0. The 3270 keystroke emulation services return codes use a function 
ID of X‘6E’. The error codes that can be received for this service are: 


Code Meaning 


X‘00’ Successful completion. 
X‘02’ Invalid session ID. 
X‘08’ An unsuccessful return code was encountered while 


processing the request. 
X‘0C’ Byte 0 of the parameter list is not 0 on the request. 


See Appendix H, “Return Codes,” for more information. 


Coding Example 


e “eo Ne 


CERETNCD 
CEFXNID 
CESESSID 
CEZERO 
CEKEYSID 
CEWRKOFF 
CEWRKSEG 


=e Me Ne 


me Me tO 


° 
’ 
* 
f 


. 
’ 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


INT 


OO0CO0000 


Connect for 3270 Keystroke Emulation 


PARAMETER LIST FOR CONNECT FOR 3270 KEYSTROKE EMULATION 


RETURN CODE 
FUNCTION NUMBER 
SESSION ID 

MUST BE ZERO 
KEYSTROKE TASK ID 
WORK AREA OFFSET 
WORK AREA SEGMENT 


=e “Se “=e Ne Ne Se Ne 


INITIALIZE PARAMETER LIST FOR CONNECT FOR 3270 KEYSTROKE EMULATION 


CERETNCD, 00H CERETNCD MUST BE O BEFORE REQUEST 
CEFXNID,0O0OH CEFXNID MUST BE O BEFORE REQUEST 
AL,SESSID SESSION ID OBTAINED FROM DEFINE 


CESESSID,AL 


PRESENTATION SPACE API 


a i nt aT eT) 


CEZERO,0 MUST BE ZERO 

AX,OFFSET WORKAREA OFFSET OF THE WORK AREA IN LIST 
CEWRKOFF ,AX 

AX,SEG WORKAREA ; SEGMENT OF THE WORK AREA IN LIST 


CEWRKSEG, AX 


AH,09H 
AL,O1H 
BH, 80H 
BL, 20H 
CX, OFFH 


INITIALIZE REGISTERS FOR CONNECT FOR 3270 KEYSTROKE EMULATION 


DX ,3270EML ; RESOLVED VALUE FOR '3270EML ' 


DI, SEG 
ES,DI 


DI,OFFSET CERETNCD 


7AH 


SEGMENT ADDRESS OF PARAMETER LIST 
IN ES 
OFFSET OF PARAMETER LIST IN DI 


CERETNCD 


se owe ‘ef 


SIGNAL WORKSTATION PROGRAM FOR CONNECT FOR 3270 KEYSTROKE EMULATION SERVICE 
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Disconnect for 3270 Keystroke Emulation 


3270 Keystroke Emulation Service X‘02’: 
3270 Keystroke Emulation 


Disconnect for 


Use this service to detach the 3270 keystroke emulation task from your PC 
presentation space that has been defined to accept 3270 keystroke 


emulation. 
Register Values 
On Request 
AH = X‘09’ 
AL = X‘02’ 
BH = X‘80’ 
BL = X‘20’ 
CX = X‘OOFF’ 
DX = Resolved value for 3270EML 
ES = Segment address of the parameter list 
DI = Offset address of the parameter list 


Parameter List Format 


[mas 


Fd re 
Offset | Length on Request on Completion 


Parameter Definitions 


Request Parameters: 
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On Completion 


BL = Return type 
CH = X‘12’ 
CL = Return code 


The contents of 
registers AX, BH, DX, 
ES, and DI are 
unpredictable. 


The session ID is the ID of the PC presentation space that was specified 
on the Connect to 3270 Keystroke Emulation request. 


The keystroke task ID must be the ID of the 3270 keystroking task 
returned on the Connect for 3270 Keystroke request. 


Return Codes 


Usage Notes 


Disconnect for 3270 Keystroke Emulation 


System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


3270 Keystroke Emulation Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the 3270 keystroke emulation management portion of the workstation 
program. The function ID is in byte 1, and the error number is in byte 
0. The 3270 keystroke emulation services return codes use a function 
ID of X‘6E’. The error codes that can be received for this service are: 


Code Meaning 


X‘00’ Successful completion. 
X ‘02’ Invalid session ID. 
X‘08’ An unsuccessful return code was encountered while 


processing the request. 
X‘0C’ Byte 0 of the parameter list is not 0 on the request. 


See Appendix H, “Return Codes,” for more information. 


You cannot request the Disconnect for 3270 Keystroke Emulation 
service while you have a Read AID Key service request outstanding. 
That is, if you have requested the Read AID Key service and specified 
asynchronous processing, you must use the Get Request Completion 
service to obtain the values on completion in the parameter list before 
you can request the Disconnect for 3270 Keystroke Emulation service. 
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Disconnect for 3270 Keystroke Emulation 


Coding Example 


° 
i 


; PARAMETER LIST FOR DISCONNECT FOR 3270 KEYSTROKE EMULATION 


‘ 

DERETNCD DB 
DEFXNID DB 
DESESSID DB 
DEZERO DB 
DEKEYSID DW 


. 
/ 


oOOoO0O0°0 


eo =e Ne Ne Ne 


RETURN CODE 
FUNCTION NUMBER 
SESSION ID 

MUST BE ZERO 
KEYSTROKE TASK ID 


; INITIALIZE PARAMETER LIST FOR DISCONNECT FOR 3270 KEYSTROKE EMULATION 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
ED 
MOV 


DERETNCD , OOH 
DEFXNID,0O0H 
AL,SESSID 
DESESSID,AL 
DEZERO,0 
AX ,KEYTSKID 


DEKEYSID,AX 


~e Ne we Ne Se Me 


: 
i 


DERETNCD MUST BE O BEFORE REQUEST 
DEFXNID MUST BE O BEFORE REQUEST 
SESSION ID OBTAINED FROM REQUEST 
TO DEFINE PRESENTATION SPACE API 
MUST BE ZERO 
KEYSTROKE TASK ID IN LIST (THE ID IS RETURN 


FROM CONNECT TO 3270 KEYSTROKE EMULATION) 


; INITIALIZE REGISTERS FOR DISCONNECT FOR 3270 KEYSTROKE EMULATION 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


. 
f 


AH,09H 

AL,O2H . 

BH, 80H 

BL, 20H 

CX, OFFH 

DX, 3270EML 

DI, SEG DERETNCD 
ES,DI 

DI,OFFSET DERETNCD 


. 
‘ 
° 
1 
. 
f 
’ 


RESOLVED VALUE FOR '3270EML ' 

SEGMENT ADDRESS OF PARAMETER LIST 
IN ES 

OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR DISCONNECT FOR 3270 KEYSTROKE EMULATION SERVICE 


. 
/ 


INT 
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7AH 


Read AID Key 


3270 Keystroke Emulation Service: Read Attention 
Identifier (AID) Key 


Register Values 


Use this service to receive AID keystrokes from the 3270 keystroke 
emulation task that is performing 3270 keystroke emulation for the 
specified presentation space. The Read AID Key service begins keystroke 
processing by enabling operator input at the keyboard of the connected 
session. As keystrokes are entered, the presentation space is updated using 
3270 keystroke rules until a valid AID key is entered. When an AID key is 
encountered, operator input to the connected session’s keyboard is again 
disabled. The Read AID key service returns the AID key in the parameter 
list in one of two formats: scan code/shift state format or ASCII mnemonic 
format. Select the ASCII format by setting the ASCII option of byte 3 of 
the parameter list upon request. The READ AID key service also returns 
the current row and column position of the cursor. 


On Request On Completion 


X‘09’ BL Return type 


BH = Synchronous or asynchronous * CH = X‘12’ 

BL = Synchronous or asynchronous * CL = Return code 

CX = X‘OOFF’ 

DX = Keystroke task ID The contents of 

ES = Segment address of the parameter list registers AX, BH, DX, 

DI = Offset address of the parameter list ES, and DI are 
unpredictable. 


* The values in these registers depend on whether you want the request to be processed 
synchronously or asynchronously. See the following description of request register values 
for more information. 


e Request Register Values: 


You can specify synchronous or asynchronous processing of the Read 
AID Key service. In synchronous processing, control is returned to 
your application program after the workstation program has completed 
the request. In asynchronous processing, control is returned to your 
application program before the workstation program has completed the 
request. You must use the Get Request Completion service to obtain 
the parameter list values on completion when you request asynchronous 
processing. 


Synchronous Processing: 

There are two ways to specify synchronous processing: 

1. Set the BH register to X‘80’ and the BL register to X‘20’. When the 
request is completed, control is returned to your application 


program and the registers and parameter list contain the values for 
completion of the request. 
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Read AID Key 


2. Set both the BH and BL registers to X‘40’. When the request is 
completed, control is returned to your program, but the parameter 
list values for completion of the request are not obtained until you 
request the Get Request Completion service. 


Asynchronous Processing: i 


For asynchronous processing of the Read AID key service request, set 
the BH register to X‘40’ and the BL register to X‘00’. When 
asynchronous processing is specified, you must request the Get Request 
Completion service to obtain the results of the Read AID Key service. 


Completion register values: 


If you specified asynchronous processing, or synchronous processing 
using X‘40’ in both the BH and BL registers on request, the AX register 
contains a request ID that the workstation program assigned to the 
request. You use this request ID to match the results of the service 
obtained by the Get Request Completion service to the results of this 
service. That is, when the request ID in the AX register, on completion 
of the Get Request Completion service, matches the request ID in the 
AX register on completion of this service, the results obtained by the 
Get Request Completion service pertain to this request. 


Parameter List Format 
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on Completion 


Scan code 
or length of mnemonic 
starting at byte 10 


Shift state 
or unchanged 


ASCII mnemonic. May 
be 2 or 4 bytes long. 


Read AID Key 


Parameter Definitions 


Request Parameters: 


The session ID is the ID of the presentation space to which the 
keystroke emulation task is attached. 


The options byte has the following values: 


— X‘00’: Previous AID key was accepted, return AID keys in 
scan/shift. 

—  X‘01’: Previous AID key was rejected, return AID keys in scan/shift. 

— X‘80’: Previous AID key was accepted, return AID keys in ASCII. 

— X‘81’: Previous AID key was rejected, return AID keys in ASCII. 


Completion Parameters: 


The scan code or length of mnemonic field (byte 6 of the parameter list) 
is a hexadecimal value that could contain one of two values: 


— Ifthe options byte was set to X‘80’ or X‘81’ upon request, byte 6 will 
contain the length of the ASCII mnemonic being returned. If this 
byte is X‘02’, then bytes 10-11 of the parameter list contain the 
2-byte ASCII mnemonic being returned, and bytes 12—13 are 
unchanged. If this byte is X‘04’, then bytes 10-13 of the parameter 
list contain the 4-byte ASCII mnemonic being returned. 


— Ifthe options byte was set to X‘00’ or X‘01’ upon request, byte 6 will 
contain the scan code of the AID key being reported. Bytes 10-138 
are unchanged. . 


The AID keys, and their associated hexadecimal scan code and ASCII 
mnemonics, are shown in the table below: 


Hexadecimal ASCII 
Scan Code Mnemonic 
AID Key Returned Returned 


Enter or CrSel 
on Ampersand 
(&) * 

Numeric Pad 
Enter 


17 


wlmi 


hur —id@s 


@ 
@ 
@ 
@ 
@ 
@ 


x‘ 
x‘ 
or idee 
xs 
Xs 


nS 


on 
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Read AID Key 


Hexadecimal ASCII 
Scan Code Mnemonic 
AID Key Returned Returned 


PF12 
PF13 
P14 


PRIS 
Pris «dix —*d 


20’ 


mei} |rHIT Oo mi Q [ol] |oO;oy] aS 


: 
3 


Space or null * 
NOE 
X‘06" @C 


* The 3270 Workstation Program uses the CrSel key the same way a light pen is used. If 
CrSel is pressed when the cursor is on a light pen detectable field, the workstation program 
may do one of four things: 


X 
X 
X 
Xx 
X 


®]®@j®©j®@] SO]©{@]@ |©@|©]® 
Ni[<|[e] Slols is ]— [rio 
. 


1. It returns an Enter AID key if the field begins with an ampersand (&). 

2. It returns the CrSel key itself if the field begins with a null or a space. 

3. It returns no AID key if the field begins with a question mark (?). The question mark 
is, however, changed to a ‘>’ and the modified data tag (MDT) bit in the field 
attribute is set on. 

‘4, It returns no AID key if the field begins with a greater than sign (>). The greater 


than sign is, however, changed to a ‘?’ and the modified data tag (MDT) bit in the field 
attribute is set off. 


9-16 


Return Codes 


Read AID Key 


If the cursor is not on a light pen detectable field, an input-inhibit condition results. 
— When the Clear key is pressed, the presentation space is cleared. 


— When all other AID keys in this table are pressed, the MDT bit is set in the field 
attribute byte of all modified fields in the presentation space. 


— The SysRq and Test keys are not supported by 3270 keystroke emulation. 
The shift state indicates the shift conditions that were active when the 


AID key was sent to your application program. The format of the shift 
byte is as follows: 


a ee see eee Ce Ce ee 
Reserved | Right | Left | Control ALT Shift | Upshift 
shift | shift | key keys Lock | keys 


— Bits 0 and 1 are reserved. 


~ Bit 2 represents the right upshift key. 

— Bit 3 represents the left upshift key. 

— Bit 4 represents the control shift state. 

— Bit 5 represents the ALT shift state. 

— Bit 6 represents the Shift Lock state. 

~— Bit 7 represents the upshift state. Bit 7 indicates that one of the 
two upshift keys was pressed. If your application program must 
distinguish between the right upshift key and the left upshift key, 
use bits 2 and 3. 


— Lower shift is represented by a value of X‘00’. 


“Cursor row” is the rew position of the cursor on the specified 
presentation space. Cursor row positions start at zero. 


“Cursor column” is the column position of the cursor on the specified 
presentation space. Cursor column positions start at zero. 


System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 
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Read AID Key 


Usage Notes 
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e 3270 Keystroke Emulation Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the 3270 keystroke emulation management portion of the workstation 
program. The function ID is in byte 1, and the error number is in byte 
0. The 3270 keystroke emulation services return codes use a function 
ID of X‘6E’. The error codes that can be received for this service are: 


Code 


X00’ 


X02’ 
X‘08’ 


X‘0C’ 


Meaning 


Successful completion. The scan code for AID key was 
returned in parameter list. 

Invalid session ID. 

An unsuccessful return code was detected while processing 
the request. 

Byte 0 of the presentation list is not 0 on the request. 


See Appendix H, “Return Codes,” for more information. 


If you specified asynchronous processing, or synchronous processing 
using X‘40’ in both the BH and BL registers on request, you must use 
the Get Request Completion service to obtain the results in the 
parameter list when the Read AID Key service is completed. 


Coding Example 


° 
, 


Read AID Key 


; PARAMETER LIST FOR READ AID KEY 


RARETNCD 
RAFXNID 

RASESSID 
RAACCREJ 


RASCNCDE 
RASHFTST 
RACURSSR 
RACURSS$C 


. 
, 


DB 
DB 
DB 
DB 
DW 
DB 
DB 
DB 
DB 


OOOC0O0O000 


RETURN CODE 

FUNCTION NUMBER 
SESSION ID 
ACCEPT/REJECT AID 
UNUSED 

SCAN CODE 

SHIFTSTATE 

CURSOR ROW POSITION 
CURSOR COLUMN POSITION 


Se a nT a eT et eT a 


; INITIALIZE PARAMETER LIST FOR READ AID KEY 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


RARETNCD , OOH 
RAFXNID,OOH 
AL,SESSID 
RASESSID,AL 
AL,ACCSREJ 
RAACCREJ, AL 


RARETNCD MUST BE O BEFORE REQUEST 
RAFXNID MUST BE O BEFORE REQUEST 
SESSION ID OBTAINED FROM REQUEST 

TO DEFINE PRESENTATION SPACE API 
ACCEPT OR REJECT PREVIOUS AID IN LIST 


eT eT eT eT 


; INITIALIZE REGISTERS FOR READ AID KEY 


° 
/ 


MOV 
MOV 
MOV 
MOV 
MOV 


MOV 
MOV 
MOV 


AH, 09H 
BH, 80H 
BL, 20H 
CX, OFFH 
DX, KEYTSKID 


DI, SEG RARETNCD 


ES,DI 


DI,OFFSET RARETNCD 


REPLY TYPE 
WAIT TYPE 
PRIORITY 


TO 3270 KEYSTROKE EMULATION 
SEGMENT ADDRESS OF PARAMETER LIST 
IN ES 
OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR READ AID KEY SERVICE 


° 
t 


INT 


7AH 
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; KEYSTROKE TASK ID RETURNED FROM CONNECT TO 
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Chapter 10. Coding Copy 


Read AID Key 


Service Requests 
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Requesting the Copy Services ......... 0.0.0: eee e eee e neces 10-3 
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Copy Service X‘01’: Copy String ........ 0... ccc cee tee ees 10-5 
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Copy Service X‘03’: Connect for Copy to PC Session ............. 10-19 

Copy Service X‘04’: Disconnect for Copy to PC Session ........... 10-22 
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Introduction 


Introduction 
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This chapter describes how to code requests for the copy services provided 
by the API. 


The copy services allow your application program to copy data into a 
personal computer window, as well as copy data from one area into another 
within the same personal computer window. The copy services also allow 
copying of data between any host and notepad sessions. (Before you can 
use a personal computer window as the target for a copy operation, you 
must use the Connect for Copy to PC Session service to designate the 
session as a valid copy target. You must also use the Disconnect for Copy 
to PC Session service when you no longer want your personal computer 
session to be a target for copy operations.) 


The copy services also allow your application program to copy data from 
one presentation space or buffer to another. Copying graphics characters 
or program symbol set characters is not allowed. 


When copying between sessions that have different character code types 
(i.e., PC characters and host/notepad characters), a translation will occur. 


The copy services provided by the API are: 


e Copy String Service: Use this service to copy a string from a 
specified presentation space or buffer into another specified 
presentation space or buffer. 


e Copy Block Service: Use this service to copy a block from a 
specified presentation space or buffer into another specified 
presentation space or buffer. 


e Connect for Copy to PC Session Service: Use this service to 
identify a personal computer session as being a valid target session for 
the copy services. 


e Disconnect for Copy to PC Session Service: Use this service to 
identify a personal computer session as no longer being a valid target 
for the copy services. 


Copy services are available for use only if you specify COPY = YES at 
customization time. 


Introduction 


The major copy operations are: copy string and copy block. The copy 
string operation copies all characters beginning with the specified starting 
character up to and including the specified ending character, as shown 
below: 


e Copy string 
If the source is specified as: 


El ow is the time for all good 
women to come to the aid of their part 


the string copied to the target is: 


Now is the time for all good 
women to come to the aid of their party 


The copy block operation copies all characters in the block of text formed 
by the specified starting and ending characters, as shown below: 


e Copy block 


If the source is specified as: 


ED} ow is the time for all good 
women to come to the aid of their part 


the block copied to the target is: 


Now is the time for all good 
men to come to the aid of their party 


Requesting the Copy Services 


To request any of the copy services, load the registers and the parameter 
list with the proper values, and use the INT 7AH instruction to signal the 
workstation program that it has a request to process. 


Note: Before your application can request the copy services, it must request 
the Name Resolution service, using ‘COPY ’ as the gate name in the 
_parameter list. (Remember that the gate name must be padded to the 

right with blanks if it is less than eight characters.) 
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Return Codes for the Copy Services 
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Each copy service has two return codes associated with it, a system return 
code and a copy service return code. Both types of return codes are 2-byte 
values made up of a function ID and an error number. The function ID 
indicates the portion of the workstation program in which the error 
occurred. The error number indicates the specific type of error that has 
occurred. An error number of X‘00’ indicates a successful acceptance or 
completion of the request. 


System Return Codes: 


After your application has requested a copy service, the CH and CL 
registers contain a return code generated by the request processing 
portion of the workstation program. The function ID is in the CH 
register, and the error number is in the CL register. System return 
codes use a function ID of X‘12’. The error codes that can appear are: 


Code Meaning 


X ‘00’ Request accepted. 

X ‘05’ Invalid index specified. 

X ‘07’ Invalid reply specified. 
X‘08’ Invalid wait type specified. 
X‘0B’ RQE pool depleted. 

X‘34’ Invalid gate entry. 


These system return codes apply to all the copy services. 
Copy Services Return Codes: 


After a requested copy service has completed, bytes 0 and 1 of the 
parameter list contain a return code generated by the copy management 
portion of the workstation program. The function ID is in byte 1, and 
the error number is in byte 0. Copy services return codes use a function 
ID of X‘64’. The error numbers that can appear are specific to the 
service that was requested, and are included in the descriptions of each 
service. 


See Appendix H, “Return Codes,” for more information. 


Copy String 


Copy Service X‘01’: Copy String 


Register Values 


Use this service to copy a string from one presentation space or buffer into 
another. 


On Request On Completion 

AH = X‘09’ CH = X‘12’ 

AL = X‘0I’ CL = Return code 

BH = X‘80’ 

BL = X‘20’ The contents of registers 
CX = X‘O0FF’ AX, BX, DX, ES, and DI 
DX = Resolved value for COPY are unpredictable. 

ES = Segment address of the parameter list 

DI = Offset address of the parameter list 


Parameter List Format 


Contents Contents 
Offset Length on Request on Completion 


jot tbyte | Must be zero [Return code 
1 1 byte Must be zero Function ID 
(X‘64’) 
2 1 byte Source session ID | Unchanged 
or zero* 
3 1 byte Reserved - must Reserved 
be X‘00’ 


Offset address of Unchanged 
source buffer or 
zero* 
1 word Segment address Unchanged 
of source buffer* 
1 byte Source Unchanged 
characteristics* 
1 byte Source session Unchanged 
type* 
10 1 word Offset of source Unchanged 
starting character 
12 1 word | Offset of source Unchanged 
ending character 
14 1 byte Target session Unchanged 
ID* or zero 


* 


The contents of this offset depend on whether a presentation space or a buffer is being used 
as the copy source/target. See the parameter definitions for more information. 
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Copy String 


Contents Contents 
Offset Length on Request on Completion 
15 1 byte Reserved - must Reserved 
be X‘00’ 
16 1 word Offset address of Unchanged 
target buffer* 
18 1 word Segment address Unchanged 
. of target buffer* 
. * 


20 1 byte Target Unchanged 

characteristics 
Target session Unchanged 
type* 
Offset of target Unchanged 
starting character 

1 byte Copy mode Unchanged 

1 byte 


* 


The contents of this offset depend on whether a presentation space or a buffer is being used 
as the copy source/target. See the parameter definitions for more information. 


Parameter Definitions 
Request Parameters: 
e Ifthe copy source is a presentation space: 


— The source session ID is the ID of the session containing the string 
to copy. 


— Offsets 3 through 9 of the parameter list must be zero. 


— The source starting character is the character offset into the 
presentation space of the starting character of the string to be 
copied. This is the number of characters, not including the 
attributes. Character offsets begin with zero. 


— The source ending character is the character offset into the 
presentation space of the ending character of the string to be 
copied. This is the number of characters, not including the 
attributes. Character offsets begin with zero. 
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Copy String 


If the copy source is a buffer: 


Offset 2 of the parameter list must be zero. 
The source buffer contains the source string for the copy. 


The source characteristics apply to DFT host sessions only as 
follows: 


If bit 7 = 0, the source has base attributes. 
If bit 7 = 1, the source has extended attributes. 


The source session type is one of the following: 


X‘02’ — DFT host session 
X‘03’ — CUT host session 
X‘04’ — notepad session 
X‘05’ — PC session 


The source starting character is the byte offset into the buffer of the 
starting character of the string to be copied. Byte offsets begin with 
zero. 


The source ending character is the byte offset into the buffer of the 
ending character of the string to be copied. Byte offsets begin with 
Zero. 


If the copy target is a presentation space: 


The target session ID is the ID of the session to receive the copied 
string. 


Offsets 15 through 21 of the parameter list must be zero. 


The target starting character is the character offset into the 
presentation space of the character to place the beginning of the 
copied string. This is the number of characters not including the 
attributes. Character offsets begin with zero. 
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Copy String 
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If the copy target is a buffer: 
— The target buffer contains the target data area for the copy. 
— Offset 14 must be zero. 


— The target characteristics apply to DFT host sessions only, and are 
as follows: 


If bit 7 = 0, the target has base attributes. 
If bit 7 = 1, the target has extended attributes. 


— The target session type is one of the following: 


X‘02’? — DFT host session 
X‘03’ — CUT host session 
X‘04’ — notepad session 
X‘05’ — PC session 


— The target starting character is the byte offset into the buffer of the 
starting character of the string to be copied. Byte offsets begin with 
Zero. 


The copy mode is specified as follows: 
— To force the desired color mode (refer to JBM 3270 Workstation 


Program User’s Guide and Reference for the definition of the color 
modes): 


X‘00’ = 4-color mode 
X‘80’ = 7-color mode 


— Ifthe target is a personal computer presentation and is connected 
for 3270 keystroke emulation or if the target is a PC buffer: 


X‘00’ 
X‘40’ 


] 


field attributes not copied 
field attributes copied 


Return Codes 


Copy String 


e System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


e Copy Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the copy management portion of the workstation program. The 
function ID is in byte 1, and the error number is in byte 0. The copy 
services return codes use a function ID of X‘64’. The error codes that 
can be received for this service are: 


Code 


X‘00’ 
X‘O1’ 
X‘02? 
X ‘03’ 
X‘05’ 
X‘06’ 


X‘07’ 
X ‘09’ 
X‘0C’ 
X‘0D’ 


X‘0E’ 
X‘OF’ 


Meaning 


Successful completion. 

Source not allowed. 

Invalid session ID. 

The target window is input-inhibited. 

The source and target areas overlap (copy performed). 
There is a missing or invalid parameter on the source 
definition. 

There is a missing or invalid parameter on the target 
definition. 

Truncation occurred (copy performed). You attempted to 
copy past the end of the presentation space. 

Byte 0 of the parameter list was not zero on request. 

The target was not allowed. 

The target window is protected. 

The copy of the field attributes was not allowed ee not 
performed). 


See Appendix H, “Return Codes,” for more information. 
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Coding Example 
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. 
‘ 


; PARAMETER LIST FOR COPY STRING 


CSRETNCD 
CSFXNID 
CSSSESID 
CSRESRV1 
CSSRCOFF 
CSSRCSEG 
CSSRCCHR 
CSSRCTYP 
CSSSTRTC 
CSSENDC 
CSTSESID 
CSRESRV2 
CSTRGOFF 
CSTRGSEG 
CSTRGCHR 
CSTRGTYP 
CSTSTRTC 
CSMODE 
CSRESRV3 


‘we Ne NO Ne te Ne 


DB 
DB 
DB 
DB 
DW 
DW 
DB 
DB 
DW 
DW 
DB 
DB 
DW 
DW 
DB 
DB 
DW 
DB 
DB 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


OO0O00000 000 00000000 


COPY THE FIRST LINE OF A NOTEPAD 


CSRETNCD , OOH 
CSFXNID,OOH 
AL,SRCSESID 
CSSSESID,AL 
CSRESRV1,0 
CSSRCOFF,0 
CSSRCSEG, 0 
CSSRCCHR,0OOH 
CSSRCTYP , 04H 
CSSSTRTC,O 
CSSENDC ,80 


CSTSESID,0 
CSRESRV2,0 
AX,OFFSET TARGET 
CSTRGOFF , AX 
AX,SEG TARGET 
CSTRGSEG , AX 
CSTRGCHR , 0 
CSTRGTYP , 05H 
CSTSTRTC,0 
CSMODE ,01000000B 


Sa i i a Re i a i i i Bn, a i i et nT eT aT 


RETURN CODE 

FUNCTION ID 

SOURCE SESSION ID 

RESERVED - MUST BE X'0OO' 

OFFSET ADDRESS OF SOURCE BUFFER 
SEGMENT ADDRESS OF SOURCE BUFFER 
SOURCE CHARACTERISTICS 

SOURCE SESSION TYPE 

OFFSET OF SOURCE STARTING CHARACTER 
OFFSET OF SOURCE ENDING CHARACTER 
TARGET SESSION ID 

RESERVED - MUST BE X'0O0' 

OFFSET ADDRESS OF TARGET BUFFER 
SEGMENT ADDRESS OF TARGET BUFFER 
TARGET CHARACTERISTICS 

TARGET SESSION TYPE 

OFFSET OF TARGET STARTING CHARACTER 
COPY MODE 

RESERVED 


TO A PC BUFFER 


INITIALIZE PARAMETER LIST FOR COPY 


me Ne Se Ne Ne Ne Ne Ne 8 Ne we Ne NO 8 Me Ne Se 8 Ne Oe Ne NO 


STRING 


RETURN CODE MUST O BEFORE REQUEST 
FUNCTION ID MUST OQ BEFORE REQUEST 
SOURCE SESSION ID INTO THE LIST 


RESERVED - MUST BE 0 

SOURCE OFFSET NOT USED 

SOURCE SEGMENT NOT USED 

SOURCE CHARACTERISTICS NOT USED 
SOURCE TYPE = NOTEPAD SESSION 
SOURCE STARTING CHARACTER OFFSET =0 
SOURCE ENDING CHARACTER OFFSET = 80 


TARGET SESSION ID NOT USED 
RESERVED - MUST BE 0 

TARGET OFFSET INTO THE LIST 
TARGET SEGMENT INTO THE LIST 
CHARACTERISTICS NOT USED 
TARGET TYPE = PC SESSION 

TARGET STARTING CHARACTER OFFSET =0 
COPY MODE = 4-COLOR WITH FIELD ATT. 


TARGET 


Copy String 


; INITIALIZE REGISTERS FOR COPY STRING 
/ 
MOV AH,O9H 
MOV AL,O1H 
MOV _—«&BH, 80H 
MOV BL,20H 
MOV CX,OFFH 
MOV DX,COPY ; RESOLVED VALUE FOR 'COPY ' 
MOV DI, SEG CSRETNCD ; SEGMENT ADDRESS OF PARAMETER LIST 
MOV ES,DI ; IN ES 
MOV DI,OFFSET CSRETNCD ; OFFSET OF PARAMETER LIST IN DI 
; SIGNAL WORKSTATION PROGRAM FOR COPY STRING SERVICE 


INT 7AH 
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Copy Service X‘02’: Copy Block 


Use this service to copy a block from one presentation space or buffer into 


another. 
Register Values 
On Request On Completion 
AH = X‘09’ CH = X‘12’ 
AL = X‘02’ CL = Return code 
BH = X‘80’ 
BL = X‘20’ The contents of registers 
CX = X‘O0FF’ AX, BX, DX, ES, and DI 
DX = Resolved value for COPY are unpredictable. 
ES = Segment address of the parameter list 


Offset address of the parameter list 


Contents Contents 
Offset Length on Request on Completion 


Must be zero Function ID 
(X‘64’) 


Reserved - must Reserved 
be X‘00’ 

Offset address of Unchanged 
source buffer or 

zero* 


Segment address Unchanged 
of source buffer* 

Source Unchanged 
characteristics* 

Source session Unchanged 
type 

Offset of source Unchanged 
starting character 

Offset of source Unchanged 
ending character 

Target session Unchanged 
ID* or zero 


The contents of this offset depend on whether a presentation space or a buffer is being used 
as the copy source/target. See the parameter definitions for more information. 
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Copy Block 


Contents Contents 
on Request on Completion 
1 byte Reserved - must Reserved 
be X‘00’ 
16 1 word Offset address of Unchanged 
target buffer* 
18 1 word Segment address Unchanged 
of target buffer* 
20 1 byte Target Unchanged 
characteristics* 
Zi 1 byte Target session Unchanged 
type* 
22 1 word Offset of target Unchanged 
starting character 
1 byte Copy mode Unchanged 
1 byte 


* 


The contents of this offset depend on whether a presentation space or a buffer is being used 
as the copy source/target. See the parameter definitions for more information. 


Parameter Definitions 
Request Parameters: 
e Ifthe copy source is a presentation space: 


— The source session ID is the ID of the session containing the block 
to copy. 


— Offsets 3 through 9 of the parameter list must be zero. 


— The source starting character is the character offset into the 
presentation space of the starting character of the block to be 
copied. This is the number of characters, not including the 
attributes. Character offsets begin with zero. 


— The source ending character is the character offset into the 
presentation space of the ending character of the block to be copied. 
This is the number of characters, not including the attributes. 
Character offsets begin with zero. 
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Copy Block 


e Ifthe copy source is a buffer: 
— Offset 2 of the parameter list must be zero. 
— The source buffer contains the source block for the copy. 


— The source characteristics apply to DFT host sessions only as 


follows: 
If bit 7 = 0, the source has base attributes. 
If bit 7 = 1, the source has extended attributes. 


— The source session type is one of the following: 


X‘02’ — DFT host session 
X‘03’ — CUT host session 
X‘04’ — notepad session 
X‘05’ — PC session 


— The source starting character is the byte offset into the buffer of the 
starting character of the block to be copied. Byte offsets begin with 
ZeYO. 


— The source ending character is the byte offset into the buffer of the 
ending character of the block to be copied. Byte offsets begin with 
zero. 


e Ifthe copy target is a presentation space: 


— The target session ID is the ID of the session to receive the copied 
block. 


~ Offsets 15 through 21 of the parameter list must be zero. 
— The target starting character is the character offset into the 
presentation space of the character to place the beginning of the 


copied block. This is the number of characters not including the 
attributes. Character offsets begin with zero. 
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Copy Block 


If the copy target is a buffer: 


Offset 14 must be zero. 
The target buffer contains the target data area for the copy. 


The target characteristics apply to DFT host sessions only, and are 
as follows: 


If bit 7 
If bit 7 


\| 


0, the source has base attributes. 
1, the source has extended attributes. 


The target session type is one of the following: 


X‘02’ — DFT host session 
X‘03’ — CUT host session 
X‘04’ — notepad session 
X‘05’ — PC session 


The target starting character is the byte offset into the buffer of the 
starting character of the block to be copied. Byte offsets begin with 
zero. 


The copy mode is specified as follows: 


To force the desired color mode (refer to IBM 3270 Workstation 
Program User’s Guide and Reference for the definition of color 
modes): 


X‘00’ 
X‘80’ 


4-color mode 
7-color mode 


If the target is a personal computer presentation and is connected 
for 3270 keystroke emulation or if the target is a PC buffer: 


X‘00’ = Field attributes were not copied 
X‘40’ = Field attributes were copied 
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Return Codes 
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e System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


e Copy Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the copy management portion of the workstation program. The 
function ID is in byte 1, and the error number is in byte 0. The copy 
services return codes use a function ID of X‘64’. The error codes that 
can be received for this service are: 


Code 


X‘00’ 
X‘01’ 
X‘02’ 
X‘03’ 
X‘05’ 
X‘06’ 
X‘07’ 
X‘09” 


X‘0C’ 
X‘0D’ 
X‘0E’ 
X‘OF”’ 


Meaning 


Successful completion. 

Source not allowed. 

Invalid session ID. 

The target window is input-inhibited. 

The source and target areas overlap (copy performed). 
There is a missing or invalid parameter on source definition. 
There is a missing or invalid parameter on target definition. 
Truncation occurred (copy performed). You attempted to 
copy past the end of the presentation space. 

Byte 0 of the parameter list was not zero on request. 

The target was not allowed. 

The target window is protected. 

A copy of the field attributes was not allowed (copy not 
performed). 


See Appendix H, “Return Codes,” for more information. 


Copy Block 


Coding Example 


ry 
, 


; PARAMETER LIST FOR COPY BLOCK 


RETURN CODE 

FUNCTION ID 

SOURCE SESSION ID 

RESERVED 

OFFSET ADDRESS OF SOURCE BUFFER 
SEGMENT ADDRESS OF SOURCE BUFFER 
SOURCE CHARACTERISTICS 

SOURCE SESSION TYPE 

OFFSET OF SOURCE STARTING CHARACTER 
OFFSET OF SOURCE ENDING CHARACTER 
TARGET SESSION ID 

RESERVED 

OFFSET ADDRESS OF TARGET BUFFER 
SEGMENT ADDRESS OF TARGET BUFFER 
TARGET CHARACTERISTICS 

TARGET SESSION TYPE 

OFFSET OF TARGET STARTING CHARACTER 
COPY MODE 

RESERVED 


CBRETNCD DB 
CBFXNID DB 
CBSSESID DB 
CBRESRV1 DB 
CBSRCOFF DW 
CBSRCSEG DW 
CBSRCCHR- DB 
CBSRCTYP DB 
CBSSTRTC DW 
CBSENDC DW 
CBTSESID DB 
CBRESRV2 DB 
CBTRGOFF DW 
CBTRGSEG DW 
CBTRGCHR DB 
CBTRGTYP DB 
CBTSTRTC DW 
CBMODE DB 
CBRESRV3 DB 


OOOO 0O0CO0O0 00000000000 


bt a a it St a eT et eT eT ee eT eT eT en) eT eT 


COPY A BLOCK FROM THE HOST TO A NOTEPAD 


INITIALIZE THE PARAMETER LIST FOR COPY BLOCK 


et eT eT 


MOV CBRETNCD,OOH ; RETURN CODE MUST = 0 BEFORE REQUEST 
MOV AL,SRCSESID ; SOURCE SESSION ID INTO THE LIST 

MOV CBSSESID,AL 

MOV CBSRCOFF,0O 

MOV  CBSRCSEG,O 

MOV CBSRCCHR,10000000B 


SOURCE OFFSET NOT USED 

SOURCE SEGMENT NOT USED 

SOURCE CHARACTERISTICS = SOURCE HAS 

EXTENDED ATTRIBUTES 

SOURCE TYPE = DFT HOST SESSION 
SOURCE STARTING CHARACTER OFFSET =0 
SOURCE ENDING CHARACTER OFFSET =835 
TARGET SESSION ID INTO THE LIST 


MOV CBSRCTYP,02H 
MOV CBSSTRTC,O 
MOV CBSENDC,835 
MOV AL,TRGSESID 
MOV CBTSESID,AL 
MOV  CBTRGOFF,O 
MOV CBTRGSEG,O 
MOV  CBTRGCHR, OOH 
MOV CBTRGTYP,04H 
MOV CBTSTRTC,440 


Tt i Bn Sl Bl Bi al) 


TARGET OFFSET NOT USED 

TARGET SEGMENT NOT USED 

TARGET CHARACTERISTICS NOT USED 

TARGET TYPE = NOTEPAD SESSION 

TARGET STARTING CHARACTER OFFSET 
= 440 

COPY MODE NOT USED 


=e Ne Ne Ne Me Ne NO 


MOV CBMODE , 0 
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Copy Block 
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aT i! aT 


° 
v 


. 
f 


INITIALIZE REGISTERS FOR COPY BLOCK 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


AH, 09H 

AL,02H 

BH, 80H 

BL, 20H 

CX, OF FH 

DX , COPY 

DI, SEG CBRETNCD 
ES,DI 

DI,OFFSET CBRETNCD 


=e Se Ne OO 


RESOLVED VALUE FOR 'COPY : 

SEGMENT ADDRESS OF PARAMETER LIST 
IN ES 

OFFSET OF PARAMETER LIST IN DI 


SIGNAL WORKSTATION PROGRAM FOR COPY BLOCK SERVICE 


INT 


7AH 


Connect for Copy to PC Session 


Copy Service X‘03’: Connect for Copy to PC Session 


Use this service to identify a personal computer session as being a valid 
target session for the copy services. 


Register Values 


On Request On Completion 

AH = X‘09’ CH = X‘12’ 

AL = X‘03’ CL = Return code 

BH = X‘80’ 

BL = X‘20’ The contents of registers 
CX = X‘OOFF’ AX, BX, DX, ES, and DI 
DX = Resolved value for COPY are unpredictable. 

ES = Segment address of the parameter list 


Offset address of the parameter list 


Parameter List Format 


Contents Contents 
eo Length on Request on Completion 


jo | a byte 


1 byte Must be zero Function ID 
(X‘64’) 


3 1 byte Reserved — must Reserved 
be X‘00’ 


Parameter Definitions 


Request Parameters: 


e The session ID is the ID of a personal computer session that will be 
identified as a valid target session for the copy services. You can 
obtain the session ID through a request to the Query Base Window 
service if this personal computer session is not one created by the 
Define Presentation Space service. 
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Connect for Copy to PC Session 


Return Codes 
e System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


e Session Information Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the copy management portion of the workstation program. The 
function ID is in byte 1, and the error number is in byte 0. The copy 
services return codes use a function ID of X‘64’. The error codes that 
can be received for this service are: 


Code Meaning 


X‘00’ Successful completion. 
X ‘02’ The specified session is not a personal computer session. 
X‘0C’ Byte 0 of the parameter list was not zero on request. 


See Appendix H, “Return Codes,” for more information. 
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Connect for Copy to PC Session 


Coding Example 


° 
f 


; PARAMETER LIST FOR CONNECT FOR COPY TO PC SESSION 


RETURN CODE 

FUNCTION NUMBER 
SESSION ID 

RESERVED -- MUST BE 0 


CCRETNCD DB 
CCFXNID DB 
CCSESSID DB 
CCRESERV DB 


OoO00 


=e “se Se NO 


; INITIALIZE PARAMETER LIST FOR CONNECT FOR COPY TO PC SESSION 


MOV CCRETNCD, OOH ; RETURN CODE MUST QO BEFORE REQUEST 
MOV CCFXNID,O0OH ; FUNCTION ID MUST QO BEFORE REQUEST 
MOV AL,SESSID ; SESSION ID INTO THE LIST 

MOV CCSESSID,AL 


ol 


; INITIALIZE REGISTERS FOR CONNECT FOR COPY TO PC SESSION 


MOV AH,09H 
MOV AL,O3H 
MOV BH,80H 
MOV BL,20H 
MOV CX,OFFH 
MOV DX,COPY ; RESOLVED VALUE FOR 'COPY ' 
MOV DI, SEG CCRETNCD ; SEGMENT ADDRESS OF PARAMETER LIST 
MOV ES,DI ; INES 
MOV DI,OFFSET CCRETNCD ; OFFSET OF PARAMETER LIST IN DI 
; SIGNAL WORKSTATION PROGRAM FOR CONNECT FOR COPY TO PC SESSION SERVICE 


INT 7AH 
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Disconnect for Copy to PC Session 


Copy Service X‘04’: Disconnect for Copy to PC Session 


Register Values 


Use this service to identify a personal computer session as no longer being 
a valid target session for the copy services. 


On Request On Completion 
AH = X‘09’ CH = X‘12’ 
AL = X‘04 CL = Return code 
- BH = X‘80’ 
BL = X‘20’ The contents of registers 
CX = X‘00FF’ AX, BX, DX, ES, and DI 
DX = Resolved value for COPY are unpredictable. 
ES = Segment address of the parameter list 


Offset address of the parameter list 


Parameter List Format 


Contents Contents 
Offset Length on Request on Completion 


jo A byte 


1 1 byte Must be zero Function ID 
(X‘64’) 


3 1 byte Reserved — must Reserved 
be X‘00’ 


Parameter Definitions 


10-22 


Request Parameters: 


e The session ID is the ID of a personal computer session that has been 
identified as a valid target session for the copy services. You can 
obtain the session ID through a request to the Query Base Window 
service if this personal computer session is not one created by the 
Define Presentation Space service. 


Disconnect for Copy to PC Session 


Return Codes 
e System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


e Session Information Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the copy management portion of the workstation program. The 
function ID is in byte 1, and the error number is in byte 0. The copy 
services return codes use a function ID of X‘64’. The error codes that 
can be received for this service are: 


Code Meaning 


X‘00’ Successful completion. 
X ‘02’ The specified session is not a personal computer session. 
X‘0C’ Byte 0 of the parameter list was not zero on request. 


See Appendix H, “Return Codes,” for more information. 
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Disconnect for Copy to PC Session 


Coding Example 
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° 
’ 


° 
‘ 


DCRETNCD DB 
DCFXNID DB 
DCSESSID DB 
DCRESERV DB 


’ 


’ 


. 
f 
. 
’ 


. 
/ 


eee ze) 


PARAMETER LIST FOR DISCONNECT FOR COPY TO PC SESSION 


RETURN CODE 

FUNCTION NUMBER 
SESSION ID 

RESERVED -- MUST BE 0 


=e “8 Ne NO 


INITIALIZE PARAMETER LIST FOR DISCONNECT FOR COPY TO PC SESSION 


MOV 
MOV 
MOV 
MOV 


DCRETNCD , OOH ; RETURN CODE MUST = O BEFORE REQUEST 
DCFXNID,0OOH ; FUNCTION ID MUST = O BEFORE REQUEST 
AL,SESSID 7 SESSION ID INTO THE LIST 
DCSESSID,AL 


INITIALIZE REGISTERS FOR DISCONNECT FOR COPY TO PC SESSION 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
‘MOV 


AH,O9H 

AL,O4H 

BH, 80H 

BL,20H 

CX , OF FH 

DX, COPY ; RESOLVED VALUE FOR 'COPY 

DI, SEG DCRETNCD ; SEGMENT ADDRESS OF PARAMETER LIST 
ES,DI ; IN ES 

DI,OFFSET DCRETNCD ; OFFSET OF PARAMETER LIST IN DI 


SIGNAL WORKSTATION PROGRAM FOR DISCONNECT FOR COPY TO PC SESSION 


INT 


7AH 


Disconnect for Copy to PC Session 
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Translate Service 


Introduction 


This chapter describes how to code requests for the translate service 
provided by the API. 


-Data that is displayed in host and notepad presentation spaces is 


represented by numbers called host/notepad character codes. Data that is 
displayed in personal computer presentation spaces is represented by ASCII 
codes. The translate service allows your application program to translate 
the data in a buffer from one type of data representation to the other. 


Notes: 


1. You cannot translate graphic characters or programmed symbol set 
characters. 


2. If the input code does not have a matching output code, it is translated to 
a blank. 


The translate service provided by the API is: 
e Translate Data Service: Use this service to translate the data in a 


buffer from ASCII codes to host/notepad character codes, or from 
host/notepad character codes to ASCII codes. 


Requesting the Translate Service 


To request the translate service, load the registers and the parameter list 
with the proper values, and use the INT 7AH instruction to signal the 
workstation program that it has a request to process. 


Note: Before your application can request the translate service, it must 
request the Name Resolution service, using ‘XLATE  ’ as the gate 
name in the parameter list. (Remember that the gate name must be 
padded to the right with blanks if it is less than eight characters.) 


Return Codes for the Translate Service 


11-2 


The translate service has two return codes associated with it: a system 
return code and a translate service return code. Both types of return codes 
are 2-byte values made up of a function ID and an error number. The 
function ID indicates the portion of the workstation program in which the 
error occurred. 

The error number indicates the specific type of error that has occurred. 
An error number of X‘00’ always indicates a successful acceptance or 
completion of the request. 


Translate Service 


e System Return Codes: 


After your application has requested a translate service, the CH and CL 
registers contain a return code generated by the request processing 
portion of the workstation program. The function ID is in the CH 
register, and the error number is in the CL register. System return 
codes use a function ID of X‘12’. The error codes that can appear are: 


Code Meaning 


X ‘00’ Request accepted. 

X‘05’ Invalid index specified. 
X‘07’ Invalid reply specified. 
X‘08’ Invalid wait type specified. 
X‘0B’ RQE pool depleted. 

X‘34’ Invalid gate entry. 


e Translate Service Return Codes: 


After a requested translate service is completed, bytes 0 and 1 of the 
parameter list contain a return code generated by the translation 
management portion of the workstation program. The function ID is in 
byte 1, and the error number is in byte 0. The translate service return 
codes use a function ID of X‘6C’. The error numbers that can appear 
are included in the description of the service. 


See Appendix H, “Return Codes,” for more information. 
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Translate Data 


Translate Service X‘01°: Translate Data 


Use this service to translate the data in a buffer from ASCIi codes to 
host/notepad character codes, or from host/notepad character codes to 
ASCII codes. 


Register Values 


On Request On Completion 
AH = X‘09’ . CH = X‘12’ 

AL = X‘01’ CL = Return code 
BH = X‘80’ 

BL = X‘20’ The contents of 

CX = X‘00FF’ registers AX, BX, 
DX = Resolved value for XLATE DX, ES, and DI are 
ES = Segment address of the parameter list unpredictable. 

DI = Offset address of the parameter list 


2 1 word Offset address of source Unchanged 
buffer 


4 1 word Segment address of source j| Unchanged 
buffer 

Offset address of target Unchanged 
buffer 

1 word Segment address of target Unchanged 
buffer 


Unchanged 
1 word Length Unchanged 
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Translate Data 


Parameter Definitions 
Request Parameters: 
e The source buffer contains the codes to be translated. 
e The target buffer is where the translated codes are to be stored. 
Note: The source and target buffers can be the same address. 
e The translate type is specified as follows: 


X‘01’—ASCII to host/notepad 
X‘02’—Host/notepad to ASCII 


e “Length” is the number of bytes to translate. If the length is 0, no 
translation occurs, but the request will not fail. 


Note: If the input code does not have a matching output code, it will be 
translated to a blank. An ASCII blank is X‘20’, and a host and 
notepad blank is X‘10’. 


The following table shows the host and notepad character codes and the 
characters they represent. 


[Ox [1x] 2x[ 3x] 4x[5x[6x]7x[8x]9x [Ax] Bx]Cx[Dx]Ex[Fx 
xOlwejsr ole lalalAlalalalalalN{alPim 
=[1[—[a fe [eel [er 


Stelalalalalere eye pal 
| tite} ]6}é]ol ele | wialw]x] - [t | 7 | 
PbS Sn Bt ee 


ADIOMIEESEACIE a 
elect [ale fale lal [T= 


isa tw a al 
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Translate Data 


Return Codes 


11-6 


Notes: 


1. 


2. 


Values X‘CO’ through X‘FF’ are used as attributes in CUT and DFT host 
sessions, and as characters in notepad sessions. 


Characters X‘68’ through X‘6F’ are replaced in the refresh buffer by 
X‘E8’, X69’, X‘6A’, X‘F8’, X‘FE’, X‘D4’, X‘CE’, and X‘D3’, respectively. 
These characters are used only in non-U.S. countries. 


The following table shows the hexadecimal ASCII codes found in the 
personal computer presentation space and the characters they represent. 


oo ele eels ee see 


BEMMBORMAIRES 


IGE 


ps| > 
ee 
Hee 
| |_| 
ALLE 
Pe] [> 
Rint 


Sac 


orlo:lo>/ps | 
Zs les Ov] =v] 29 
| | 


%[e|s 10/0 ORE + |>|#/¢/</0/0 
PET tt elie a [Sl] a | 
2[V | ILA ]+-[+ holeo foun] [eo|ro 
ZS ic) (lO) amb [ole|> 
> |=|/|-|N|</<[=]</¢)5[/a/0 
|B [ote on|]@ [alo [ora 
Fs ea ol lol Gate CcEnalE) 


Nf [fe Ee] EF] [ee leclealae! =] 
sc dd 


For further information regarding the personal computer character set and 
attributes, refer to the [BM Personal Computer Technical Reference. 


System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


Translate Data 


e Translate Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the translate management portion of the workstation program. The 
function ID is in byte 1, and the error number is in byte 0. Translate 
services return codes use a function ID of X‘6C’. The translate services 
return codes that can be received for this service are: 


Code Meaning 


X‘00’ Successful completion. 
X‘01’ Invalid translate type. 
X‘0C’ Byte 0 in the parameter list was not zero on request. 


See Appendix H, “Return Codes,” for more information. 
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Translate Data | 


Coding Example 
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° 
‘ 
o 
‘ 


PARAMETER LIST FOR TRANSLATE DATA 


; 
TLRETNCD 


DB 0O : 
TLFXNID DB O ; 
TLSRCOFF DW 0O ; 
TLSRCSEG DW 0O H 
TLTRGOFF DW 0O Hi 
TLTRGSEG DW 0O ; 
TLTYPE DB O ; 
TLRESERV DB O : 
TLLENGTH DW 0O ; 


RETURN CODE 

FUNCTION NUMBER 

OFFSET ADDRESS OF SOURCE BUFFER 

SEGMENT ADDRESS OF SOURCE BUFFER 
OFFSET ADDRESS OF TARGET BUFFER 

SEGMENT ADDRESS OF TARGET BUFFER 
TRANSLATE TYPE 

RESERVED 

LENGTH 


; INITIALIZE PARAMETER LIST FOR TRANSLATE DATA 


MOV TLRETNCD,OOH ; 
MOV TLFXNID,OOH ; 
MOV AX,OFFSET SOURCE ; 
MOV TLSRCOFF,AX 
MOV AX,SEG SOURCE ; 
MOV TLSRCSEG,AX 
MOV AX,OFFSET TARGET ; 
MOV TLTRGOFF,AX 
MOV AX,SEG TARGET : 
MOV TLTRGSEG,AX 
MOV TLTYPE,O1H ; 
MOV TLLENGTH,80 ; 

f 

; INITIALIZE REGISTERS FOR TRANSLATE 
MOV AH,O9H 
MOV. AL,O1H 
MOV BH, 80H 
MOV BL,20H 
MOV CX,OFFH 
MOV DX,XLATE : 
MOV DI, SEG TLRETNCD_ ; 
MOV ES,DI : 
MOV DI,OFFSET TLRETNCD ; 


. 
f 


RETURN CODE MUST = 
FUNCTION ID MUST = 
SOURCE OFFSET INTO 


O BEFORE REQUEST 
0 BEFORE REQUEST 
THE LIST 


| 


SOURCE SEGMENT INTO THE LIST 
TARGET OFFSET INTO THE LIST 
TARGET SEGMENT INTO THE LIST 


TRANSLATE ASCII TO EBCDIC 
TRANSLATE 80 BYTES 


DATA 


RESOLVED VALUE FOR 'XLATE ' 

SEGMENT ADDRESS OF PARAMETER LIST 
IN ES 

OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR TRANSLATE DATA SERVICE 


° 
V 


INT 7AH 


Translate Data 
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Introduction 


Introduction 


12-2 


This chapter describes how to code requests for the operator information 
area (OIA) services provided by the API. 


The OIA services allow your application program to determine the current 
status of a session as shown in the OIA. 


The OIA services provided by the API are: 


e Read Operator Information Area Image Service: Use this service 
to obtain an image of the OIA for the specified session. 


e Read Operator Information Area Group Service: Use this service 
to obtain a bit string that indicates the current settings of a group of 
indicators in the OJA for the specified session. 


The Read Operator Area Image service reads an image of the OIA into a 
buffer that you supply. In order for the image to be useful to you, you must 
be aware of the possible OIA indicators that can be displayed on the system 
you are connected to. To determine the presence of a particular OJA 
indicator, you must scan the buffer for the hexadecimal character that 
represents that character. The OIA image in the buffer is represented by 
host/notepad character codes. 


The Read Operator Area Group service returns a bit mask that indicates 
the state of all the indicators in a specified group of OIA indicators. The 
states of each group are ordered so that the high-order bits represent the 
indicators of higher priority. Therefore, if more than one state is active 
within a group, the state with the highest priority is the active state within 
that group. 


Notes: 


1. For CUT host sessions, the information in the OIA may not be updated to 
reflect the status of that session if the session has lost communication 
with the controller or the host. 


2. For non-3270 PC hardware, no OIA is displayed for PC sessions. In 
addition, there is no host separation line in the OIA. 


For more information on the host OIA, refer to the 3278 Display Station 
Operator’s Guide. 


For further information on the OIJA, refer to the IBM 3270 Workstation 
Program User’s Guide and Reference. 


OIA Service 


Requesting the Operator Information Area Services 


To request the operator information area services, load the registers and 
the parameter list with the proper values, and use the INT 7AH instruction 
to signal the workstation program that it has a request to process. 


Note: Before your application can request the operator information area 


services, it must request the Name Resolution service, using 

‘OIAM * as the gate name in the parameter list. (Remember that 
the gate name must be padded to the right with blanks if it is less 
than eight characters.) 


Return Codes for the Operator Information Area Services 


Each operator information area service has two return codes associated 
with it, a system return code and an operator information area services 
return code. Both types of return codes are 2-byte values made up of a 
function ID and an error number. The function ID indicates the portion of 
the workstation program in which the error occurred. The error number 
indicates the specific type of error that has occurred. An error number of 
X‘00’ always indicates a successful acceptance or completion of the request. 


System Return Codes: 


After your application has requested an operator information area 
service, the CH and CL registers contain a return code generated by the 
request processing portion of the workstation program. The function ID 
is in the CH register, and the error number is in the CL register. 

System return codes use a function ID of X‘12’. The error codes that 
can appear are: 


Code Meaning 


X‘00’ Request accepted. 
X‘05’ Invalid index specified. 
X‘07’ Invalid reply specified. 


X‘08’ Invalid wait type specified. 
X‘0B’ RQE poo! depleted. 
X‘OF’ Invalid environment access. 


X‘34’ Invalid gate entry. 


These system return codes apply to all the operator information area 
services. 


Operator Information Area Services Return Codes: 


After a requested operator information area service is completed, bytes 
0 and 1 of the parameter list contain a return code generated by the 
OIA management portion of the workstation program. The function ID 
is in byte 1, and the error number is in byte 0. Operator information 
area services return codes use a function ID of X‘6D’. The error 
numbers that can appear are specific to the service that was requested 
and are included in the descriptions of each service. 


See Appendix H, “Return Codes,” for more information. 
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Read Operator Information Area Image 


Operator Information Area Service X‘01’: Read Operator 
Information Area Image 


Use this service to obtain an image of the operator information area for the 
specified host, notepad, or PC session (excluding WSCtr! mode). 


Register Values 


On Request On Completion 
AH = X‘09’ CH = X‘12’ 

AL = X‘0OV CL = Return code 
BH = X‘80’ 

BL = X‘20’ The contents of 

CX = X‘00FF’ registers AX, BX, 
DX = Resolved value for OIAM DX, ES, and DI are 
ES = Segment address of the parameter list unpredictable. 


DI = Offset address of the parameter list 


Parameter List Format 


Offset address of OIA buffer 


Segment address of OIA Unchanged 
buffer 


Parameter Definitions 
Request Parameters: 


e The session ID is the ID of the session being queried for OIA 
information. 


e The OIJA buffer is the buffer where the OIA image data will be returned. 
The OIA buffer must be 160 bytes long. Each character in the OIA is 
represented in the buffer by two bytes of information. The first byte 
contains the character in the OIA, and the second byte contains the 
character attribute for that character. Figures F-3 and F-5 in 
Appendix F, “Presentation Space Considerations,” show the format of 
the character attributes and the hexadecimal codes for the OIA 
characters. 
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OIA Image Overlay 


Return Codes 


Read Operator Information Area Image 


Below are some useful byte definitions; their byte positions start with 
offset 0. 


Byte Meaning 


36 Window short name. 

38 Screen profile number. 

104 Autokey play/record status. 
106 Autokey abort/pause status. 
110 Enlarge state. 

118 Printer status. 


System Return Codes: 


Refer to the chapter introduction for a description of the system 
return codes found in the CH and CL registers. 


Operator Information Area Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated 
by the OIA management portion of the workstation program. The 
function ID is in byte 1, and the error number is in byte 0. The OIA 
return codes use a function ID of X‘6D’. The error codes that can be 
received for this service are: 


Code Meaning 


X‘00’ Successful completion. 
X‘02’ Invalid session ID. 
X‘0C’ Byte 0 of the parameter list was not zero on request. 


See Appendix H, “Return Codes,” for more information. 


Usage Notes 


In order for the OIA image to be useful, you must be aware of the 
possible OIA indicators that can be displayed on the system you are 
connected to. 


To determine the presence of a particular OIA indicator, you must 
scan the buffer for the hexadecimal character that represents that 
character. The OIA image in the buffer is represented by 
host/notepad character codes. 
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Read Operator Information Area Image 


e When this service is requested for a CUT host session, the following 
OIA indicators are not returned: 


— Autokey input inhibited (found in Group 8) 
— Autokey states (found in Groups 16 and 17) 
— Enlarge state (found in Group 18) 


To obtain these indicators for a CUT host session, use the Read 
Operator Information Area Group service. 


e For CUT host sessions, the information in the OIA may not be 
updated to reflect the status of that session if the session has lost 
communication with the controller or the host. 


Coding Example 


. 
f 


; PARAMETER LIST FOR READ OPERATOR 


OIRETNCD 


DB O ; 
OIFXNID DB 0O ; 
OISESSID DB 0 : 
OIRESVD DB 0O . 
OIAOFFS DW 0 i 
OIASEGM DW O ; 


; INITIALIZE PARAMETER LIST FOR READ 


MOV OIRETNCD,OOH ; 
MOV OIFXNID,OOH ; 
MOV AL,SESSID ; 
MOV OISESSID,AL F 
MOV AX,OFFSET OIABUFF ; 
MOV OIAOFFS,AX : 
MOV AX,SEG OIABUFF : 
MOV OIASEGM,AX : 


INFORMATION AREA IMAGE 


RETURN CODE 

FUNCTION ID 

SESSION ID 

RESERVED 

OFFSET ADDRESS OF OIA BUFFER 
SEGMENT ADDRESS OF OIA BUFFER 


OPERATOR INFORMATION AREA IMAGE 


RETURN CODE MUST = O BEFORE REQUEST 
FUNCTION ID MUST = O BEFORE REQUEST 
SESSION ID OBTAINED FROM REQUEST 

TO QUERY SESSION ID SERVICE 

OFFSET OF THE OIA BUFFER 

IN PARAMETER LIST 

SEGMENT ADDRESS OF OIA BUFFER 

IN PARAMETER LIST 


; INITIALIZE REGISTERS FOR READ OPERATOR INFORMATION AREA IMAGE 


MOV AH,O9H 
MOV AL,O1H 
MOV ‘BH, 80H 
MOV BL, 20H 
MOV CX, OFFH 
MOV DX,OIAM : 
MOV DI, SEG OIRETNCD ; 
MOV ES,DI F 
MOV DI,OFFSET OIRETNCD ; 


° 
a 


NAME RESOLUTION FOR OIAM 

SEGMENT ADDRESS OF PARAMETER LIST 
IN ES 

OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR READ OPERATOR INFORMATION AREA IMAGE 


SERVICE 


a 
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Read Operator Information Area Group 


Operator Information Area Service X‘02’: Read Operator 
Information Area Group 


Use this service to obtain a bit string that indicates the current settings 
of a group of indicators in the operator information area for the 
specified session. 


Register Values 


On Request 

AH = X‘09’ 

AL = X‘02’ 

BH = X‘80’ 

BL = X‘20’ 

XX = X‘OOFF’ 

DX = Resolved value for OIAM 

ES = Segment address of the parameter list 
DI = Offset address of the parameter list 


Parameter List Format 


Ie ad 
1 
2 
4 
eo! 


Contents Contents 
Offset | Length | on Request on Completion 


OIA group number 


1 byte 


1 byte Must be zero Function ID 
(X‘6D’) 


1 word Offset address of OIA Unchanged 
buffer 

1 word Segment address of OIA Unchanged 
buffer 


On Completion 


CH = X‘12’ 
CL = Return code 


The contents of 
registers AX, BX, 
DX, ES, and DI are 
unpredictable. 
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Read Operator Information Area Group 


Parameter Definitions 


Request Parameters: 


e The session ID is the ID of the session being queried for OIA 
information. 


e The OIA buffer is the buffer where the OIA group data will be 
returned. The buffer sizes for each group are as follows: 


Groups 1 through 7: 1 byte 


Group 8: 5 bytes 


Groups 9 through 18: 1. byte 


All groups (group number X‘FF’): 22 bytes 


e The group number is the number of the requested OIA group. To 
obtain indicators for all OIA groups, specify group number X‘FF’. 


OIA Group Indicator Meanings 
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The states of each group are ordered so that the high-order bits 
represent the indicators of higher priority. Therefore, if more than one 
state is active within a group, the state with the highest priority is the 
active state within that group. 


The meanings of the bits in each OIA group are as follows: 


e Group 1: Online and screen ownership 


Bit 


0 


ooh OD = 


9 


7 


Meaning 

Setup mode 

Test mode 

SSCP-LU session owns screen 
LU-LU session owns screen 
Online and not owned 
Subsystem ready 

Reserved 


e Group 2: Character selection 


Bit 


0 


o ® © DO = 


Meaning 
Extended select 
APL 

Kana 

Alpha 

Text 

Reserved 


NTS of © DS HK © 
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Shift state 


Meaning 
Upper shift 
Numeric 
Reserved 


PSS group 1 


Meaning 
Operator-selectable 
Field inherit 
Reserved 


Highlight group 1 
Meaning 
Operator-selectable 
Field inherit 


Reserved 


Color group 1 


- Meaning 


Operator-selectable 
Field inherit 
Reserved 

Insert 
Meaning 
Insert mode 
Reserved 


Input inhibited (5 bytes) 


Meaning 


Nonresettable machine check 
Reserved for security key 


Machine check 
Communication check 
Program check 

Retry 

Device not working 
Device very busy 
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Bit Meaning 

Device busy 
Terminal wait 
Minus symbol 
Minus function 
Too much entered 
Not enough entered 
Wrong number 
Numeric field 


TQ of WD FH SO 


pte 
oe 


Meaning 

Reserved 

Operator unauthorized 

Operator unauthorized, minus function 
Invalid dead key combination 

Wrong place 

Reserved 


oR WD me © eo 


| 
~] 


Bit Meaning 

0 Message pending 

1 Partition wait 

2 System wait 

3 Hardware mismatch 

4 Logical terminal not configured at control unit 
5-7 Reserved 


Bit Meaning 

0 Autokey inhibit 

1 Application program has operator input inhibited 
2-7 Reserved 


Group 9: PSS group 2 


Bit Meaning 
0 PS selected 
1 PC display disable 


2-7 Reserved 
Group 10: Highlight group 2 


Bit Meaning 
0 Selected 


A -~ 7 Reserved 


Group 11: Color group 2 


Bit Meaning 
0 Selected 
1-7 Reserved 


Group 12: 


Bit 

0 

1 
ya 


Group 13: 


Bit 
0 


Oo or OD 


cae | 
Group 14: 
Group 15: 


Group 16: 


Group 17: 


Bit 

0 

1 
2-7 


Group 18: 


Read Operator Information Area Group 


Communication error reminder 


Meaning 
Communication error 
Response time monitor 
Reserved 


Printer status 


Meaning 

Print code not customized 
Printer malfunction 
Printer printing 

Assign printer 

What printer 

Printer assignment 
Reserved 


Reserved group 

Reserved group 

Autokey play/record status 
Meaning 

Play 

Record 

Reserved 

Autokey abort/pause state 
Meaning 

Recording overflow 

Pause 

Reserved 

Enlarge state 

Meaning 


Window is enlarged 
Reserved 
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Read Operator Information Area Group 


Return Codes 
e System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


e Operator Information Area Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the OIA management portion of the workstation program. The function 
ID is in byte 1, and the error number is in byte 0. The OJA return codes 
use a function ID of X‘6D’. The error codes that can be received for this 
service are: 


Code Meaning 


X‘00’ Successful completion. 
X‘02’ Invalid session ID. 
X‘0C’ Byte 0 of the parameter list was not zero on request. 


See Appendix H, “Return Codes,” for more information. 


Usage Notes 
e For CUT host sessions, the information in the OIA may not be updated 


to reflect the status of that session if the session has lost 
communication with the controller or the host. 
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Read Operator Information Area Group 


Coding Example 


° 
a 


; PARAMETER LIST FOR READ OPERATOR INFORMATION AREA GROUP 


RETURN CODE 

FUNCTION ID 

SESSION ID 

RESERVED 

OFFSET ADDRESS OF OIA BUFFER 
SEGMENT ADDRESS OF OIA BUFFER 
OIA GROUP NUMBER 


OGRETNCD DB 
OGFXNID DB 
OGSESSID DB 
OGRESVD DB 
OGBUFOFF DW 
OGBUFSEG DW 
OGGRPNUM DB 


OOCOCO0O00 


se Ne Ne Ne Ne Ne Ne 


; INITIALIZE PARAMETER LIST FOR READ OPERATOR INFORMATION AREA GROUP 


MOV OGRETNCD,OOH 

MOV OGFXNID,OOH 

MOV AL,SESSID 

MOV OGSESSID,AL 

MOV AX,OFFSET OIABUFF 
MOV OGBUFOFF,AX 

MOV AX,SEG OIABUFF 
MOV OGBUFSEG,AX 

MOV AL,5 

MOV OGGRPNUM,AL 


RETURN CODE MUST = 0 BEFORE REQUEST 
FUNCTION ID MUST = 0 BEFORE REQUEST 
SESSION ID OBTAINED FROM REQUEST 

TO QUERY SESSION ID SERVICE 

OFFSET OF THE OIA BUFFER 

IN PARAMETER LIST 

SEGMENT ADDRESS OF OIA BUFFER 

IN PARAMETER LIST 

OIA GROUP NUMBER 

IN PARAMETER LIST 


Tt a et i! eT eT eT eT eT | 


; INITIALIZE REGISTERS FOR READ OPERATOR INFORMATION AREA GROUP 
MOV AH,O9H 
MOV AL,O2H 
MOV BH,80H 
MOV BL,20H 
MOV CX,OFFH 
MOV DX,OIAM ; NAME RESOLUTION FOR OIAM 
MOV DI, SEG OGRETNCD ; SEGMENT ADDRESS OF PARAMETER LIST 
MOV ES,DI ; IN ES 
MOV DI,OFFSET OGRETNCD ; OFFSET OF PARAMETER LIST IN DI 
; SIGNAL WORKSTATION PROGRAM FOR READ OPERATOR INFORMATION AREA GROUP 
SERVICE 


’ 


INT 7AH 
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Read Operator Information Area Group 
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Introduction 


Introduction 


This chapter describes how to code requests for the Multi-DOS support 
services provided by the API. 


The Multi-DOS support services allow your application program to query 
the size in paragraphs of a specified environment, and to request DOS INT 
21H function calls asynchronously. 


The Multi-DOS support services provided by the API are: 


e Query Environment Size: Use this service to obtain the size in 
paragraphs of the specified environment, the address of the first 
paragraph of the environment, and a flag describing the state of the 
environment. 


e Asynchronous DOS Function Request: Use this service to issue 
DOS function requests asynchronously. 


e Get Storage: Use this service to allocate storage to your application 
program. This service performs the same function as the DOS INT 21H 
type 48 function call. 


e Free Storage: Use this service to free storage from your application 
program. This service performs the same function as the DOS INT 21H 
type 49 function call. 


e Set Storage Allocation: Use this service to modify the number of 
blocks of storage allocated to your application program. This service 
performs the same function as the DOS INT 21H type 4A function call. 


Requesting the Multi-DOS Support Services 
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To request the Multi-DOS support services, load the registers and the 
parameter list with the proper values, and use the INT 7AH instruction to 
signal the workstation program that it has a request to process. 


Note: Before your application can request the Multi-DOS support services, it 
must request the Name Resolution service, using ‘INDJQRY ’, 
‘INDJASY ’, or ‘MEMORY as the name in the parameter list. 
(Remember that the name must be padded to the right with blanks if it 
is less than eight characters.) 


Introduction 


Return Codes for the Multi-DOS Support Services 


Each Multi-DOS support service has two return codes associated with it, a 
system return code and a Multi-DOS support services return code. Both 
types of return codes are 2-byte values made up of a function ID and an 
error number. The function ID indicates the portion of the workstation 
program in which the error occurred. The error number indicates the 
specific type of error that has occurred. An error number of X‘00’ always 
indicates a successful acceptance or completion of the request. 


System Return Codes: 


After your application has requested a Multi-DOS support service, the 
CH and CL registers contain a return code generated by the request 
processing portion of the workstation program. The function ID is in 
the CH register, and the error number is in the CL register. System 
return codes use a function ID of X‘12’. The error codes that can 
appear are: 


Code Meaning 


X‘00° Request accepted. 

X‘05’ Invalid index specified. 
X‘07’ Invalid reply specified. 
X‘08’ Invalid wait type specified. 
X‘0B’ RQE pool depleted. 

X‘OF’ Invalid environment access. 
X ‘34’ Invalid gate entry. 


These system return codes apply to all the Multi-DOS support services. 
Multi-DOS Support Services Return Codes: 


After a requested Multi-DOS support service is completed, bytes 0 and 1 
of the parameter list contain a return code generated by the Multi-DOS 
support management portion of the workstation program. The function 
ID is in byte 1, and the error number is in byte 0. Multi-DOS support 
service return codes use function IDs X‘22’ and X‘23’. The error 
numbers that can appear are specific to the service that was requested 
and are included in the descriptions of each service. 


See Appendix H, “Return Codes,” for more information. 
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Query Environment Size 


Multi-DOS Support Service: Query Environment Size 


Use 


this service to obtain the size in paragraphs of the specified 


environment, the address of the first paragraph of the environment, and a 
flag describing the state of the environment. 


Register Values 


On Request On Completion 

AH = X‘09’ CH = X‘12’ or X‘13’ 
BH = X‘80’ CL = Return code 
BL = X‘20’ . 

CX = X‘FF’ The contents of 

DX = Resolved value for INDJQRY registers AX, BX, 
ES = Segment address of the parameter list DX, ES, and DI are 
DI = Offset address of the parameter list unpredictable. 


Request Register Values: 


The DX register contains the resolved value of the component name 
INDJQRY. Your application must request the Name Resolution service 
using INDJQRY as the name in the parameter list to obtain this 
resolved value. 


Parameter List Format 


Contents Contents 
Offset | Length on Request on Completion 


Parameter Definitions 


Request Parameters: 
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The environment ID is the ID of the environment being queried. © 


Return Codes 


Query Environment Size 


Completion Parameters: 


The bits in the environment flag are as follows: 
jo 
Stopping/ | Reserved | DOS Reserved| Base | Keybd 

running appl wait 
— Bit 0 set to 1 indicates that the environment is stopping, doing an 


IPL, or involved in an INDSPLIT or INDMERGE operation. Bit 0 
set to 0 indicates that the environment is in a normal running state. 


— Bits 1 and 2 are reserved. 


— Bit 3 set to 1 indicates that COMMAND.COM is the base 
application. 


— Bits 4 and 5 are reserved. 


— Bit 6 set to 1 indicates that the base-level program (the application 
specified at customization time) is running. 


— Bit 7 set to 1 indicates that the program is in a keyboard wait. 
The environment size is the number of paragraphs in the environment. 


The environment address is the segment address of the beginning of the 
environment. 


System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


Multi-DOS Support Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the Multi-DOS management portion of the workstation program. The 
function ID is in byte 1, and the error number is in byte 0. The 
Multi-DOS support services return codes use a function ID of X‘22’. 
The error codes that can be received for this service are: 


Code Meaning 


X ‘00’ Successful completion. 
X‘E6’ Byte 0 of the parameter list was not zero on request. 
X‘E7’ Invalid environment ID. 


See Appendix H, “Return Codes,” for more information. 
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Query Environment Size 


Coding Example 
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. 
vA 


. 
f 


Ul 

QDRETNCD DB 
QDFXNID DB 
QDENVID DB 
QDENVFLG DB 
QDENVSIZ DW 
QDENVADD DW 


’ 


’ 


, 


O0O0000 


=e §e Ne Ne Me ft 


PARAMETER LIST FOR QUERY ENVIRONMENT SIZE 


RETURN CODE 
FUNCTION ID 
ENVIRONMENT ID 
ENVIRONMENT FLAG 
ENVIRONMENT SIZE 
ENVIRONMENT ADDRESS 


INITIALIZE PARAMETER LIST FOR QUERY ENVIRONMENT SIZE 


MOV 
MOV 
MOV 
MOV 


QDRETNCD , OOH 
QDFXNID, OOH 
AL,ENVID 
QDENVID,AL 


=e Se Ne ONO 


QDRETNCD MUST BE O BEFORE REQUEST 
QDFXNID MUST BE O BEFORE REQUEST 
ENVIRONMENT ID 

IN LIST 


INITIALIZE REGISTERS FOR QUERY ENVIRONMENT SIZE 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


AH, 09H 
BH, 80H 

BL, 20H 

CX, OFFH 

DX, INDJQRY ; 
DI, SEG QDRETNCD_ ; 
ES ,DI ; 
DI,OFFSET QDRETNCD ; 


RESOLVED VALUE FOR INDJQRY 

SEGMENT ADDRESS OF PARAMETER LIST 
IN ES 

OFFSET OF PARAMETER LIST IN DI 


SIGNAL WORKSTATION PROGRAM FOR QUERY ENVIRONMENT SIZE SERVICE 


INT 


7AH 


Asynchronous DOS Function Requests 


Multi-DOS Support Service: Asynchronous DOS 
Function Requests 


Register Values 


Use this service to issue DOS function requests. 


The Multi-DOS portion of the workstation program provides a special task 
for personal computer applications to issue DOS interrupt 21H function 
calls asynchronously. For example, an application program could use this 
service to perform a DOS function call for file I/O, and continue processing 
without having to wait for the I/O to be completed. 


On request, the parameter list for the Asynchronous DOS Function 
Requests service contains the register values needed for the DOS function 
being requested. On completion, the parameter list contains the register 
values that were set by the DOS function. 


At least three separate requests have to be issued to use this function: a 
connect for asynchronous DOS function requests, one or more 
asynchronous DOS function requests, and a disconnect for asynchronous 
DOS function requests. 


Note: DOS function calls 0H, 81H, 4B00H, 4CH, and 4DH cannot be 
requested using this service. Requests for these DOS function calls 
will fail with return code X‘11’, invalid function. This service should 
not be used for display or keyboard I/O, because the results will be 


unpredictable. 

On Request On Completion 

AH = X‘09’ AX = Return ID 

BH = Synchronous or asynchronous * BL = Return type 

BL = Synchronous or asynchronous * CH = X‘12’ or X‘13’ 

CX = X‘FF’ CL = Return code 

DX = Resolved value for INDJASY 

ES = Segment address of the parameter list The contents of 

DI = Offset address of the parameter list registers BH, DX, 
ES, and DI are 
unpredictable. 


* The values in these registers depend on whether you want the request to be processed 
synchronously or asynchronously. See the description of request register values for more 
information. 


e Request Register Values: 
The DX register contains the resolved value of the name INDJASY. 
Your application must request the Name Resolution service using 


INDJASY as the name in the parameter list to obtain this resolved 
value. 
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Asynchronous DOS Function Requests 
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You can specify synchronous or asynchronous processing of the 
Asynchronous DOS Function Requests service. In synchronous 
processing, control is returned to your application program after the 
workstation program has completed the request. In asynchronous 
processing, control is returned to your application program before the 
workstation program has completed the request. You must use the Get 
Request Completion service to obtain the parameter list values on 
completion when you request asynchronous processing. 


Synchronous Processing: 
There are two ways to specify synchronous processing: 


1. Set the BH register to X‘80’ and the BL register to X‘20’. When the 
request is completed, control is returned to your application 
program and the registers and parameter list contain the values for 
completion of the request. 


2. Set both the BH and BL registers to X‘40’. When the request is 
completed, control is returned to your program, but the parameter 
list values for completion of the request are not obtained until you 
request the Get Request Completion service. 


Asynchronous Processing: 


For asynchronous processing of the Asynchronous DOS Function 
Requests service request, set the BH register to X‘40’ and the BL 
register to X‘00’. When asynchronous processing is specified, you must 
request the Get Request Completion service to obtain the results of the 
Asynchronous DOS Function Requests service. 


Completion Register Values: 


If you specified asynchronous processing, or synchronous processing 
using X‘40’ in both the BH and BL registers on request, the AX register 
contains a request ID that the workstation program assigned to the 
request. You use this request ID to match the results of the service 
obtained by the Get Request Completion service to the results of this 
service. That is, when the request ID in the AX register, on completion 
of the Get Request Completion service, matches the request ID in the 
AX register on completion of this service, the results obtained by the 
Get Request Completion service pertain to this request. 


Asynchronous DOS Function Requests 


Parameter List Format 


[om ies [erie [Ss 
Offset | Length on Request on Completion 


4 1 word AX register value Value determined by 
DOS function 
1 word BX register value Value determined by 
DOS function 
1 word CX register value Value determined by 
DOS function 
10 1 word DX register value Value determined by 
DOS function 


1 word DS register value Value determined by 
DOS function 

1 word ES register value Value determined by 
DOS function 

1 word SI register value Value determined by 
DOS function 

1 word DI register value Value determined by 
DOS function 

1 word Flags register value Value determined by 
DOS function 


Parameter Definitions 
Request Parameters: 
e The request type can be one of the following: 


X‘00’ — to connect for asynchronous DOS function requests 
X‘01’ — to request a DOS function 
X‘02’ — to disconnect for asynchronous DOS function requests 


You must use request type X‘00’ to connect for asynchronous DOS 
function requests before you can use request type X‘01’ to request a 
DOS function. When your application program has completed all its 
DOS function requests, it must use request type X‘02’ to disconnect for 
asynchronous DOS function requests. 


e The remainder of the parameter list must contain the values of registers 
AX, BX, CX, DX, DS, ES, SI, and DI and the flags register. The values 
in these registers should correspond to the values needed by the DOS 
function you are requesting. The registers that are not used by the 
DOS functions do not need to be set or initialized to any value. 


Chapter 13. Coding Multi-DOS Support Service Requests 13-9 


Asynchronous DOS Function Requests 


Return Codes 


Usage Notes 
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System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


Multi-DOS Support Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the Multi-DOS management portion of the workstation program. The 
function ID is in byte 1, and the error number is in byte 0. The 
Multi-DOS support services return codes use a function ID of X‘23’. 
The error codes that can be received for this service are: 


Code | Meaning 

X ‘00’ Successful completion 

X‘Ol’ through X‘53’ DOS interrupt 21H errors 

X‘FD’ Not connected for asynchronous DOS requests 


See Appendix H, “Return Codes,” for more information. 


If you specified asynchronous processing, or synchronous processing 
using X‘40’ in both the BH and BL registers on request, you must use 
the Get Request Completion service to obtain the results in the 
parameter list when the Asynchronous DOS Function Requests service 
is completed. 


If your system extension is going to use DOS function calls, it is 
recommended that you use the Multi-DOS support services, because 
those services do not use the interrupt vectors to issue the request, 
which allows ill-behaved application programs to run simultaneously. 


Asynchronous DOS Function Requests 


Coding Example 


° 
’ 
. 
’ 


ARRETNCD 
ARFXNID 
ARTYPE 
ARRESRVD 
ARSAX 
ARSBX 
ARSCX 
ARSDX 
ARSDS 
ARSES 
ARSSI 
ARSDI 
ARFLAGS 


ue Me Ne 


O0O00C0CO0O0CO0C0000 


yet et er  ) eT ee a? eT] 


~e Ne Ne 


e 
tf 


° 
ta 
. 
a 


PARAMETER LIST FOR ASYNCHRONOUS DOS FUNCTION REQUESTS 


RETURN CODE 
FUNCTION NUMBER 
ENVIRONMENT ID 
RESERVED 

AX REGISTER 

BX REGISTER 

CX REGISTER 

DX REGISTER 

DS REGISTER 

ES REGISTER 

SI REGISTER 

DI REGISTER 
FLAGS 


INITIALIZE PARAMETER LIST FOR ASYNCHRONOUS DOS FUNCTION REQUESTS 


SMRETNCD MUST BE O BEFORE REQUEST 
SMFXNID MUST BE O BEFORE REQUEST 
REQUEST TYPE IN THE LIST 


PUT THE CURRENT FLAGS INTO THE LIST 


PRINT A STRING 


PUT THE OFFSET AND SEGMENT OF THE STRING 
INTO THE LIST 


REGISTERS FOR ASYNCHRONOUS DOS FUNCTION REQUESTS 


MOV ARRETNCD,OOH 
MOV ARFXNID,OOH 
MOV AL,1l 
MOV ARTYPE,AL 
PUSHF 
POP  ARFLAGS 
MOV ARSAX,0900H 
MOV ARSDX,OFFSET STRING 
MOV ARSDS,SEG STRING 
; INITIALIZE 
MOV AH,O9H 
MOV BH,80H 
MOV BL,20H 
MOV CX,OFFH 
MOV DX,INDJASY 
MOV DI, SEG ARRETNCD 
MOV ES,DI 
MOV DI,OFFSET ARRETNCD 


. 
, 


e 
a 
° 
7 
tA 
. 
t 
, 
i 
f 


REPLY TYPE IN BH 

WAIT TYPE IN BL 

PRIORITY IN CX 

RESOLVED VALUE FOR 'INDJASY ' 

SEGMENT ADDRESS OF PARAMETER LIST 
IN ES 

OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR ASYNCHRONOUS DOS FUNCTION REQUESTS 


SERVICE 


, 


INT 


7AH 
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Get Storage 


Multi-DOS Support Service X‘01’: Get Storage 


Register Values 


Use this service to allocate storage to your application program. This 
service performs the same function as the DOS INT 21H type 48 function 


call. 


On Request On Completion 

AH = X‘09’ CH = X‘12’ or X‘13’ 
AL = X0V CL = Return code 
BH = X‘80’ 

BL = X‘20’ The contents of 

CX = X‘FF’ registers AX, BX, 
DX = Resolved value for MEMORY DX, ES, and DI are 
ES = Segment address of the parameter list unpredictable. 

DI = Offset address of the parameter list 


e Request Register Values: 


The DX register contains the resolved value of the gate name 
MEMORY. Your application must request the Name Resolution service 
using MEMORY as the gate name in the parameter list to obtain this 
resolved value. 


Parameter List Format 
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Fe a 
Offset | Length on Request on Completion 

fo [1byte | Must be zero ‘(Return code 
ae 


1 word Paragraphs Unchanged or 
paragraphs free 


Get Storage 


Parameter Definitions 


Request Parameters: 


The environment ID is the ID of the environment to perform the request 
in. 


“Paragraphs” is the number of 16-byte paragraphs of storage to allocate. 


Completion Parameters: 


Return Codes 


“Paragraphs free” is the number of 16-byte paragraphs that are free, if 
insufficient storage was available for the request. Otherwise, this value 
is unchanged from its request value. 


“Segment” is the segment address of the start of the allocated block of 
storage. 


System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


Multi-DOS Support Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the Multi-DOS management portion of the workstation program. The 
function ID is in byte 1, and the error number is in byte 0. The 
Multi-DOS support services return codes use a function ID of X‘23’. 
The error codes that can be received for this service are: 


Code Meaning 


X‘00’ Successful completion. 

X‘07’ Storage control blocks destroyed. 
X ‘08’ Insufficient storage. 

X‘ET’ Invalid environment ID. 


See Appendix H, “Return Codes,” for more information. 


Usage Notes 


An application running in a stoppable environment can only get storage 
from its own environment. 
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Get Storage 


Coding Example 
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° 
, 


° 
s 


GMRETNCD DB 
GMFXNID DB 
GMENVID DB 
GMRESRVD DB 
GMPARAGN DW 
GMSEGMNE DW 


! 


, 


. 
‘ 


° 
‘ 


. 
f 


oOOoO0O000 


PARAMETER LIST FOR GET STORAGE 


“eo ‘Ne we Se Ne Ne 


RETURN CODE 

FUNCTION NUMBER 
ENVIRONMENT ID 

RESERVED 

NUMBER OF PARAGRAPHS 
SEGMENT ADDRESS OF MEMORY 


INITIALIZE PARAMETER LIST FOR GET STORAGE 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


GMRETNCD , OOH 
GMFXNID, 00H 
AL ,ENVID 
GMENVID, AL 
AX , NUMPARAG 
GMPARAGN , AX 


. 
, 
e 
Ul 
tf 
‘ 
. 
f 
° 
f 


GMRETNCD MUST BE O BEFORE REQUEST 
GMFXNID MUST BE O BEFORE REQUEST 
ENVIRONMENT ID 
IN LIST 
NUMBER OF PARAGRAPHS TO ALLOCATE 
IN LIST 


INITIALIZE REGISTERS FOR GET STORAGE 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


AH ,09H 

AL,O1H 

BH, 80H 

BL,20H 

CX , OFFH 

DX , MEMORY 

DI, SEG GMRETNCD 
ES ,DI 

DI,OFFSET GMRETNCD 


. 
? 
° 
i 
° 
‘ 
fa 


SIGNAL WORKSTATION PROGRAM FOR GET 


INT 


7AH 


RESOLVED VALUE FOR 'MEMORY ‘' 

SEGMENT ADDRESS OF PARAMETER LIST 
IN ES 

OFFSET OF PARAMETER LIST IN DI 


STORAGE SERVICE 


Free Storage 


Multi-DOS Support Service X‘02’: Free Storage 


Use this service to free storage from your application program. This 
service performs the same function as the DOS INT 21H type 49 function 


call. 
Register Values 
On Request 
AH = X‘09’ 
AL = X‘02’ 
BH = X‘80’ 
BL = X‘20’ 
CX = X‘FF’ 
DX = Resolved value for MEMORY 
ES = Segment address of the parameter list 
DI = Offset address of the parameter list 


e Request Register Values: 


On Completion 


X‘12’ or X‘13’ 
Return code 


CH 
CL 


il 


The contents of 
registers AX, BX, 
DX, ES, and DI are 
unpredictable. 


The DX register contains the resolved value of the gate name 
MEMORY. Your application must request the Name Resolution service 
using MEMORY as the gate name in the parameter list to obtain this 


resolved value. 


Parameter List Format 


Parameter Definitions 


Request Parameters: 


oe [gs [Ee [Ee 
Offset | Length on Request on Completion 

[o_[ibyte | Must be zero ~~‘ Return code 
re [1word _[Sogment | Unchanged 


e The environment ID is the ID of the environment to perform the request 


in. 


e “Segment” is the segment adress of the start of the block of storage to 


free. 
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Return Codes 
e System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


e Multi-DOS Support Services Return Codes: 
Bytes 0 and 1 of the parameter list contain a return code generated by 
the Multi-DOS management portion of the workstation program. The 
function ID is in byte 1, and the error number is in byte 0. The 
Multi-DOS support services return codes use a function ID of X‘23’. 
The error codes that can be received for this service are: 
Code Meaning 
X‘00’ Successful completion. 
X‘07’ Storage control blocks destroyed. 
X‘09’ Invalid storage block address. 


X‘E7’ Invalid environment ID. 


See Appendix H, “Return Codes,” for more information. 


Usage Notes 


e An application running in a stoppable environment can only free 
storage from its own environment. 
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Free Storage 


Coding Example 


° 
ti 


; PARAMETER LIST FOR FREE MEMORY 


RETURN CODE 

FUNCTION NUMBER 
ENVIRONMENT ID 

RESERVED 

NUMBER OF PARAGRAPHS 
SEGMENT ADDRESS OF MEMORY 


FMRETNCD DB 
FMF XNID DB 
FMENVID DB 
FMRESRVD DB 
FMPARAGN DW 
FMSEGMNE DW 


OoOO0C0000 


Sa St Ml al eT | 


; INITIALIZE PARAMETER LIST FOR FREE MEMORY 


MOV FMRETNCD , OOH ; FMRETNCD MUST BE O BEFORE REQUEST 
MOV FMFXNID,OOH ; FMFXNID MUST BE O BEFORE REQUEST 
MOV AL, ENVID ; ENVIRONMENT ID 


MOV FMENVID,AL IN LIST 
MOV AX,SEGADDR SEGMENT ADDRESS OF BLOCK 
MOV FMSEGMNE , AX TO FREE 


; INITIALIZE REGISTERS FOR FREE MEMORY 


MOV AH,O9H 
MOV AL,O2H 

MOV BH,80H 

MOV BL,20H 

MOV CX,OFFH 

MOV DX,MEMORY ; RESOLVED VALUE FOR 'MEMORY ' 

MOV DI, SEG FMRETNCD ; SEGMENT ADDRESS OF PARAMETER LIST 
MOV ES,DI ; IN ES 

MOV DI,OFFSET FMRETNCD ; OFFSET OF PARAMETER LIST IN DI 


SIGNAL WORKSTATION PROGRAM FOR FREE MEMORY SERVICE 


~e Me Ne 


INT 7AH 
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Set Storage Allocation 


Multi-DOS Support Service X‘03’: Set Storage Allocation 


Register Values 


Use this service to modify the number of blocks of storage allocated to your 
application program. This service performs the same function as the DOS 
INT 21H type 4A function call. 


On Request On Completion 

AH = X‘09’ CH = X‘12’ or X‘13’ 
AL = X‘03’ CL = Return code 
BH = X‘80’ 

BL = X‘20’ The contents of 

CX = X‘FF’ registers AX, BX, 
DX = Resolved value for MEMORY DX, ES, and DI are 
ES = Segment address of the parameter list unpredictable. 


DI Offset address of the parameter list 


e Request Register Values: 


The DX register contains the resolved value of the gate name 
MEMORY. Your application must request the Name Resolution service 
using MEMORY as the gate name in the parameter list to obtain this 
resolved value. 


Parameter List Format 
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Contents Contents 

Offset | Length on Request on Completion 
ro [1 byte 
Function 1D O35) 
Unchanged 
1 byt 

1 word Paragraphs Unchanged or 
io oe free 


[6 [tword [Segment | Unchanged 


Set Storage Allocation 


Parameter Definitions 


Return Codes 


Usage Notes 


Request Parameters: 


The environment ID is the ID of the environment to perform the request 
in. 


“Paragraphs” is the number of 16-byte paragraphs to set the block size 
to. 


“Segment” is the segment address of the block of storage to be set. 


Completion Parameters: 


“Paragraphs free” is the maximum number of 16-byte paragraphs that 
the block can grow to, if insufficient storage was available for the 
request. Otherwise, this value is unchanged from its request value. 


System Return Codes: 


Refer to the chapter introduction for a description of the system return 
codes found in the CH and CL registers. 


Multi-DOS Support Services Return Codes: 


Bytes 0 and 1 of the parameter list contain a return code generated by 
the Multi-DOS management portion of the workstation program. The 
function ID is in byte 1, and the error number is in byte 0. The 
Multi-DOS support services return codes use a function ID of X‘23’. 
The error codes that can be received for this service are: 


Code Meaning 


X‘00’ Successful completion. 

X‘07’ Storage control blocks destroyed. 
X‘08’ Insufficient storage. 

X‘09’ Invalid storage block address. 
X‘E7’ Invalid environment ID. 


See Appendix H, “Return Codes,” for more information. 


An application running in a stoppable environment can only set storage 
from its own environment. 
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Set Storage Allocation 


Coding Example 
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e se Ne 


PARAMETER LIST FOR SET MEMORY 


SMRETNCD DB 
SMFXNID DB 
SMENVID DB 
SMRESRVD- DB 
SMPARAGN DW 
SMSEGMNE DW 


° 
f 
. 
t 


° 
Ld 


. 
i 


’ 


. 
, 
. 
I 


. 
a 


OO0O0000 


we Ne Ne Ne we NO 


RETURN CODE 

FUNCTION NUMBER 
ENVIRONMENT ID 

RESERVED 

NUMBER OF PARAGRAPHS 
SEGMENT ADDRESS OF MEMORY 


INITIALIZE PARAMETER LIST FOR SET MEMORY 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


INITIALIZE REGISTERS FOR SET MEMORY 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


SMRETNCD , OOH 
SMFXNID, 00H 
AL,ENVID 
SMENVID,AL 
AX , NUMPARAG 
SMPARAGN , AX 
AX , SEGADDR 
SMSEGMNE , AX 


AH, 09H 

AL,0O3H 

BH, 80H 

BL, 20H 

CX, OFFH 

DX , MEMORY 

DI, SEG SMRETNCD 
ES,DI 

DI,OFFSET SMRETNCD 


=e Ne Ne Ne Ne NBN NO 


e 
a 
f 
. 
f 
° 
la 


SIGNAL WORKSTATION PROGRAM FOR SET 


INT 


7AH 


SMRETNCD MUST BE O BEFORE REQUEST 
SMFXNID MUST BE O BEFORE REQUEST 
ENVIRONMENT ID 

IN LIstT 
PARAGRAPH NUMBER 

IN LIST 
SEGMENT ADDRESS 

IN LIST 


RESOLVED VALUE FOR 'MEMORY  ' 

SEGMENT ADDRESS OF PARAMETER LIST 
IN ES 

OFFSET OF PARAMETER LIST IN DI 


MEMORY SERVICE 


Part 3. Supervisor Services 


This part contains information about the supervisor services of the 
application programming interface. 


Chapter 14, “Supervisor Services,” describes the types of supervisor 
services provided by the workstation program that your application 
program can use. 


Chapter 15, “Coding Supervisory Object Services,” describes the 
supervisory object services that your application program can use. 


Chapter 16, “Coding Request Services,” describes the task/component 
request services that your application program can use. 


Chapter 17, “Coding Task State Modifier Services,” describes the task 
state modifier services that your application program can use. 


Chapter 18, “Coding Semaphore Management Services,” describes the 
semaphore management request services that your application program 
can use. . 


Chapter 19, “Coding Logical Timer Management Services,” describes 
the logical timer management request services that your application 
program can use. 


Chapter 20, “Coding Fixed-Length Queue Management Services,” 
describes the fixed-length queue management request services that your 
application program can use. 


Chapter 21, “Coding Interrupt Handler Management Services,” 


describes the interrupt handler management services that your 
application program can use. 


Part 3. Supervisor Services 


e Chapter 22, “Environments and the Environment Manager,” describes 
environments, environment access restrictions, and resource managers. 


e Chapter 23, “Coding Environment Manager Services,” describes the 
environment manager services that your application program can use. 


e Chapter 24, “Coding System Extensions,” describes how to code and 
use system extensions as part of the control program. 


Conventions Used in the API Service Descriptions 


The following conventions are used in the descriptions of the API services: 


e Hexadecimal numbers are represented in the notation X‘nn’ for byte 
values and X‘nnnn’ for word values. 


e Offsets into data structures used by the API services are given as 
decimal numbers. 


e Bits within a byte are numbered with the high-order (leftmost) bit as bit 
0 and the low-order (rightmost) bit as bit 7, as follows: 


fo fa fae 
ae eee ae eee ee 


This order of bit numbering follows the IBM 360/370 convention and is the 
reverse of the Intel 8088 bit-numbering convention. 
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Global Software Interrupt Handlers ..................0006 

Software Interrupt Handler Considerations ................ 
Interrupt Handler Management Services Your Application 

Program: Can, Use: . i534 oh abe eRe NEE a RRO DER EMEM TES 


Introduction 


The supervisor portion of the Workstation Program provides a set of system 
services that support a multitasking environment. Supervisor services are 
divided into the following categories: 

e Supervisory object creation and deletion 

e Task/component requests 

e Task state modifiers 

e Semaphore management 

e Logical timer management 

e Fixed-length queue management 


e Interrupt handler management. 


Each of these categories of supervisor services is discussed below. 


Supervisory Object Creation and Deletion 


Tasks 


The supervisor manages the following supervisory objects: 

e Tasks 

e Components 

e Semaphores 

e Fixed-length queues 

e Gates 

e User exit tables. 

The supervisor manages supervisory objects through entries in the SVC 


table. A list of the supervisory object services that your application 
program can request is given at the end of this section. 


A task is a unit of dispatchable code. If the tasks are scheduled for 
execution by the dispatcher and are ready to run, they are guaranteed to 
execute (where components must be invoked). Conceptually, a task is a 
never-terminating program. Tasks can perform work on behalf of other 
system objects, including other tasks. They are capable of both 
synchronous and asynchronous communication. 
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Components 


14-4 


All tasks run on their own stacks and are serially reusable (that is, not 
reentrant). 


There are 64 priority levels in the system. When you write an application 
program, it runs at priority 60. Your application, however, can issue the 
Create Task Entry service to create a task that runs at a priority of your 
choice between 36 and 64. Your system extension may also create a task to 
run at any priority between 1 and 64. 


For an example of a task or for the Create Task Entry service with coding 
instructions, see Chapter 15, “Coding Supervisory Object Services.” 


Components represent shared code that can be dynamically invoked. Since 
they are shared, they should either be reentrant or use code serialization 
techniques (for example, semaphores). 


Components are invoked through the Make Request system service. When 
they get control, the registers are set up just as if the component had done 
a Get Request. Once a component is invoked, it is running under the task 
thread of the invoking task. Because a component runs under a task 
thread, it can perform any function a task can perform. However, a 
component must be very careful in relying on the state of certain task 
resources, such as the request and completion queues. Since a task can do 
asynchronous processing, it may have outstanding signals that may arrive 
after a component has been invoked. Therefore, a component does not 
necessarily have free use of a task’s wait states. In general, a component 
can freely wait on a fixed-length queue or a semaphore; but any other wait 
can interfere with a task’s asynchronous processing. 


If a component uses other services that require use of wait states, they 
should clearly document what restrictions are imposed on the invocation of 
the component. For example, if the component uses the Make Request 
service and waits for a completion signal, it must be clearly documented 
that no outstanding completion signals can be pending when this 
component is invoked. 


As a general guideline, tasks should use completion signals only for 
synchronous services (request and wait) and should use completion queue 
signals for either synchronous or asynchronous requests. This ensures that 
components can use the completion signal facility to implement their 
required function. 


Note: When a component is invoked through the Make Request service, the 
requested wait must be a completion signal, and the requested reply 
must be a completion signal, In implementation, the task is not put to 
sleep. Instead, it remains dispatchable. However, on each dispatch the 
component, running under the task thread, is dispatched. The 
invoking task’s code will only be executed after the component returns. 


Requests to components are passed by means of a parameter list. 
Components receive the address of the parameter list in the ES and DI 
registers and the requester’s ID in the DX register. 


See Chapter 15, “Coding Supervisory Object Services,” for an example of 
how to create a component. 


When a component is done executing, it must do a Return Far. 


Semaphores 


Semaphores are system objects that allow system designers to guarantee 
serial access to a resource. When a task owns a semaphore, it is assured 
that it is the only supervisory object that can access the resource protected 
by the semaphore. 


There are two types of semaphores: resource semaphores and code 
serialization semaphores. Code serialization semaphores have some 
restrictions placed on them in respect to environment access. These 
restrictions are described under “Semaphore Management” in this chapter. 


In essence, semaphores represent resource locks. However, this locking is 
only by agreement. That is, in order for a semaphore to be effective, all 
tasks must. “agree” to claim the semaphore before accessing a desired 
resource, code, or data. If a task violates this agreement, the integrity of a 
system design may be in jeopardy. 


Access to semaphores is granted on a first-in-first-out (FIFO) basis. 
Semaphore ownership is granted to tasks. This means that a component is 
not considered to own a semaphore. If a component claims a semaphore, 
that semaphore is owned by the task the component is running under. 


Fixed-Length Queues 


Fixed-length queues are queues that exist in an application program’s 
address space but that are managed by the supervisor. Fixed-length queues. 
are used by the supervisor to report events and pass keystrokes typed on 
the keyboard to your application program. They are also useful for 
application programs that must send small amounts of data between them. 
In asense, fixed-length queues represent a “pipeline” between two 
cooperating tasks. 


Fixed-length queues are managed on a FIFO basis, use a circular linking 
structure, and have a fixed size. You determine the structure and length of 
the elements enqueued and dequeued from a fixed-length queue, on the 
basis of the needs of your particular application program. 
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Gates 


A gate is a grouping of services provided by a system extension that can be 
accessed by tasks or components. A gate contains a list of component or 
task IDs. Each component or task ID is associated with a specified service 
provided by the gate. The services provided by the gate are requested 
through the use of the Task/Component Request services, described under 
“Task Request Services Your Application Program Can Use” on page 14-9. 


A gate should have a name assigned to it. Typically, the gate name 
indicates the type of services provided by the gate. 


User Exit Tables 


A user exit table is basically a branch table. It is made up of a series of 
32-bit values, generally the segment and offset addresses of entry points to 
routines. Your application program can write routines to run whenever 
control is passed to their addresses in the user exit table. By giving a user 
exit table a name that an application program can name-resolve, your 
system extension can allow an application program to replace these 
routines with its own. This is useful for functions such as error handling. 


The Supervisor Call Instruction (SVC) Table 


The supervisor makes an entry in a table called the SVC table for each 
supervisory object defined in the system. The supervisor uses these entries 
to manage task and component requests, and to control access to 
semaphores, fixed-length queues, user exit tables, and gates. The supervisor 
identifies each supervisory object by a numeric index. This numeric index 
is referred to as the ID of the object. 


Creating Objects with Names 


Each entry in the SVC table can have a unique eight-byte name associated 
with it. If the name is less than eight characters, you should pad it to the 
right with blanks. All names must be unique, with one exception: an 
object in a stoppable environment may have a name that is a duplicate of a 
name in another stoppable environment. The name is useful for objects 
that are to be known outside their environment. The Name Resolution 
supervisor service returns the numeric ID of the supervisory object 
associated with a specified name. The ID Resolution supervisor service 
returns the name associated with the supervisory object specified by its 
numeric ID. 
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Supervisory Object Services Your Application Program Can Use 
The supervisory object services provided by the API are: 


e Create Task Entry: Use this service to create an entry in the SVC 
table for a task. 


e Create Component Entry: Use this service to create an entry in the 
SVC table for a component. 


e Create Semaphore Entry: Use this service to create an entry in the 
SVC table for a semaphore. 


e Create Fixed-Length Queue Entry: Use this service to create an 
entry in the SVC table for a fixed-length queue. 


e Create Gate Entry: Use this service to create an entry in the SVC 
table for a gate. 


e Create User Exit Table Entry: Use this service to create an entry 
in the SVC table for a user exit table. 


e Install User Exit Table Entries: Use this service to install entries 
in the specified user exit table. 


e Name Resolution: Use this service to resolve the specified 
supervisory object name to its numeric index. 


e ID Resolution: Use this service to resolve the specified supervisory 
ID name to its alphanumeric name. 


e Delete Entry: Use this service to delete an entry in the SVC table 
representing the specified supervisory object. 


These services are described in Chapter 15, “Coding Supervisory Object 
Services.” 


Task Requests 


Tasks, components, and interrupt handlers represent the only code in the 
system. In a multitasking system, it is necessary for a task, the primary 
object, to request services of other tasks. 


This request structure is supported by a variable-length request queue and 
a variable-length completion queue in each task control block. Tasks pass 
information about requests and request completion through the use of 
request queue elements (RQEs). 
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Use of Wait States 
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A task can wait for one or more events. These events are typically referred 
to as signals (that is, a task waits for specific types of signals). The seven 
types of signals for which a task can wait are: 


e ‘Request queue’ signal 

e Gneistiea queue’ signal 
e ‘Completion’ signal 

e ‘Semaphore’ signal 

e ‘Timer’ signal 

e ‘Generic’ signal 

e ‘Data available’ signal 


Each of these signals is associated with a specific event. The first three 
signals (‘request queue,’ ‘completion queue,’ and ‘completion’) are all 
associated with the task request structure. Whenever a task uses the Make 
Request system service, it specifies what events it wants to wait for and 
what kind of reply should be sent to the task after the request has been 
completed. If it specifies a reply of ‘completion queue’ signal, the RQE 
associated with the request is placed on the task’s completion queue, and a 
‘completion queue’ signal is generated to the task when the request has 
been finished. If the task specifies a reply of ‘completion’ signal, the RQE 
associated with the request is not returned when the request has been 
finished. Therefore, it is not necessary to invoke a Get Request Completion 
system service. However, a ‘completion’ signal is generated to the task. 


The ‘request queue’ signal is sent whenever a request (RQE) is placed onto 
a task’s request queue. Therefore, a task can be in a “Get Request loop” 
waiting for a request to be placed on its request queue. 


A ‘semaphore’ signal is generated whenever a task invokes the Claim a 
Semaphore system service with a “wait for semaphore free” wait state, and 
ownership of the semaphore is granted to the requesting task. Once the 
‘semaphore’ signal is sent, the task is removed from the waiting state. The 
wait for semaphore free option is only meaningful when a task invokes the 
Claim a Semaphore system service. 


Once a task has received a timer, it can use the Set Timer system service. 
After the timer is running, the task can specify a “wait for ‘timer’ signal” 
option on any system service that allows the wait option to be specified 
(this would normally be done when the timer is set). When the timer counts 
down, a ‘timer’ signal is sent to the task that owns the timer. If the task 
was waiting for a ‘timer’ signal, it is then removed from the wait state. 


A task can wait for a ‘generic’ signal. Any task can send a ‘generic’ signal 
to any other task (environment restrictions apply). Therefore, a ‘generic’ 
signal is a means for two tasks to cooperate and communicate in a primitive 
manner. No meaning is attached to the ‘generic’ signal other than that 
which cooperating tasks assign to it. 


Whenever a task requests data from a fixed-length queue, there may not be 
enough data in the queue to satisfy its request. If the request specifies a 
“wait for data” option, the task will be taken out of the wait state when 
some other task in the system enqueues enough data to satisfy the dequeue 
request. The “wait for data” option is only meaningful when the Dequeue 
system service is invoked. 


Sending a Request to Another Task 


When a task requests a service of another task, the supervisor obtains an 
RQE, fills it in with the details of the request (including a pointer to a 
parameter list and the type of reply desired), and enqueues the RQE on the 
requested task’s request queue. Parameter lists sent to a task must reserve 
the first two bytes as a return code field to be used by the workstation 
program. 


The requesting task specifies what type of wait state it will be set to. The 
task can specify a multiple-wait state, which ends when any one of the wait 
conditions is satisfied. The requesting task also specifies what type of reply 
it expects when the request is completed. Possible reply types include no 
reply, reply via a ‘completion’ signal, or reply via an RQE on the requesting 
task’s completion queue. For example, a task can request a service, 
specifying that it will wait for an RQE on its completion queue, and expect 
a reply in the form of an RQE on its completion queue. 


Requests can be made to tasks or components. When they are directed at 
components, the wait requested must be a ‘completion’ signal. The system 
will simply call the component, passing in registers the details of the 
request. 


Receiving a Request from Another Task 


A task that receives requests can be in a never-terminating loop, waiting to 
get requests. The task can do this by invoking the Get a Request service 
and specifying that it wants to wait until an RQE is enqueued on its 
request queue. When an RQE is enqueued on this task’s request queue, the 
task is set to the “dispatchable” state. The registers of this task will 
contain the details of the request. 
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Replying to a Request from Another Task 


The requested task can now service the request and use the Reply to a 
Request service to send a reply and the request-completion information to 
the requesting task. When a task issues the Reply to a Request service, the 
supervisor removes the RQE from the task’s request queue, examines it for 
the type of reply specified by the requesting task, and sends that reply to 
the requesting task. 


Obtaining Request Completion from Another Task 


The supervisor notifies the requesting task that the request has been 
completed by sending it the type of reply specified on the request. If the 
requesting task specified that it wanted an RQE placed on its completion 
queue, it must use the Get Request Completion service to obtain the 
completion values of the registers and parameter list. 


Task Request Services Your Application Program Can Use 
The task/component request services provided by the API are: 


e Make a Request: Use this service to put a request queue element on 
a task’s request queue, or to directly invoke a component. 


e Geta Request: Use this service to obtain the contents of a request 
queue element (which includes a parameter list) on a task’s request 
queue. A component does not have to do this. When a component gets 
control, the parameter list passed to it is pointed to by the ES and DI 
registers. 


e Reply toa Request: Use this service to remove a specified request 
queue element from a task’s request queue and to send the specified 
reply to the requester. A component does not need to do this. You 
must get a request before you can reply to it. 


e Get Request Completion: Use this service to obtain the contents of 
a request queue element from a task’s completion queue. A component 


does not need to do this. It simply checks the parameter list. 


e Send a Signal to a Task: Use this service to send a signal to the 
specified task. 


These services are described in Chapter 16, “Coding Request Services.” 
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Task State Modifiers 


Dispatch Cycles 


Tasks are the only dispatchable units of code in the system. The dispatcher 
portion of the workstation program is responsible for scheduling and 
dispatching a task on each dispatch cycle. 


Dispatch cycles are driven by both hardware interrupts and voluntary 
relinquishment of the processor by a task. Because the workstation 
program is time-sliced, a dispatch cycle is guaranteed as often as hardware 
timer interrupts occur. A dispatch cycle occurs whenever: 


e A first-level interrupt handler has finished processing. 
e A task enters the “wait” or “unready” state. 


e A task requests the Return to Dispatcher service, so that another task 
can be run. 


Task Dispatching Procedure 


Tasks are selected for dispatching by scanning the dispatch list. The 
dispatch list contains an entry for each task priority level (1 through 64). 
Each entry on the dispatch list consists of a status flag and a pointer to the 
first task control block (TCB) at that priority. The TCB of each task points 
to the TCB of the next task at the same priority. The last task in the TCB 
chain for each priority points to the first task in the chain. This type of 
chain is called a round-robin chain. 


Dispatch List 


Round-Robin Chain 
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The dispatcher selects the next task to be dispatched as follows: 


e The dispatcher first determines the highest dispatchable priority. If the 
last task to run at that priority is nonpreemptable within its 
round-robin and dispatchable, it is selected for dispatching. Otherwise, 
the next dispatchable task at that priority is selected. 


e Ifthe currently selected task has another task in its environment that: 
had been running as nonpreemptable within the environment and did 
not voluntarily (by a requested wait or dispatch return request) give up 
control, that other task is selected instead for dispatching. 


Task Dispatch Activity 
Each time a task is dispatched, the following occurs: 


1. The execution state (hardware flags and registers) is saved on the 
currently active task’s stack. 


2. The active task’s SS and SP registers are saved. 
3. The next task to be dispatched is selected. 


4. The selected task’s execution state is restored from its stack, and the 
task is set running through the use of an IRET instruction. 


Task Dispatcher States | 


The dispatch status of each task is contained in the task’s TCB. The 
possible dispatch states are as follows: 


Dispatchable The task is eligible to be dispatched. It is 
not in a wait, unready, or suspended state. 


Wait The task cannot be dispatched. It is 
waiting for one or more of the following: 


e A request queue element in its request 
queue 

e A request queue element in its 
completion queue 


e A ‘completion’ signal 
e A ‘semaphore claimed’ signal 
e A ‘timer tick’ signal 
e_ A ‘data available’ signal 
e A ‘generic’ signal. 
Unready The task cannot be dispatched. The 


unready state ends when a task receives a 
‘ready’ signal. 
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Suspend The task cannot be dispatched. This state 


usually applies to all tasks within the same 
environment, while the unready state 
applies to a specific task only. The suspend 
state ends when the task becomes 
unsuspended. 


Pending Unready The resource manager puts the task in the 


“unready” state after it releases all code 
serialization semaphores. 


Nonpreemptable within round robin 


The task will continue to be selected for 
dispatching as long as no task at a higher 
priority becomes dispatchable. 


Nonpreemptable within environment 


The task will continue to be dispatched any 
time any task within its environment has 
been selected for dispatching. A task that 
is nonpreemptable within its environment is 
not nonpreemptable within its round-robin 
chain and, therefore, competes for the 
processor with tasks of equal and higher 
priority. 


Task State Modifier Services Your Application Program Can Use 


The task state modifier services provided by the API are: 


Query Active Task: Use this service to obtain the ID and priority of 
the currently active task. 


Set Task “Ready”: Use this service to set a specified task to the 
“ready” state. 


Set Task “Unready”: Use this service to set a specified task to the 
“unready” state. 


Set Task “Preemptable”: Use this service to set a specified task to 
the “preemptable” state. 


Set Task “Nonpreemptable”: Use this service to set a specified task 
to the “nonpreemptable” state. 


Change Task’s Priority: Use this service to change the specified 
task’s priority. 


Return to Dispatcher: Use this service to return to the dispatcher 
from the requesting task. 


These services are described in Chapter 17, “Coding Task State Modifier 
Services.” 
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Semaphore Management 


Semaphores are supervisory objects that allow your application program to 
control access to resources and the execution of nonreentrant code. 
Resource semaphores control access to resources, and code serialization 
semaphores control the execution of nonreentrant code. 


Considerations for Using Code Serialization Semaphores 


Code serialization semaphores protect segments of code in stoppable 
environments that should not be interrupted by stop or suspend functions. 
When a stop or suspend service is requested for an environment, the 
workstation program waits for all code serialization semaphores to be 
released by the tasks in the environment before honoring the stop or 
suspend request. Therefore, it is recommended that your application 
program release any code serialization semaphores it has claimed before it 
requests any service that causes the program to enter a dispatcher wait 
state. 


In addition, there are times when the workstation program itself stops or 
suspends an environment. Your application program must release any code 
serialization semaphores before these stop or suspend requests can be 
completed. The workstation program issues stop or suspend requests on an 
environment at the following times: 


e When you use the Split Environment or Merge Environment commands. 
The workstation program attempts to stop all environments involved in 
the split or merge operation. 


e When you jump (either by using the window management services or 
the Jump key) to a window that contains an application that writes 
directly to the interrupt vectors. The workstation program attempts to 
suspend the application in the window you jumped from. 


e When another application program becomes active, and the previously 
active application has claimed a code serialization semaphore and also 
violates any of the rules listed in Chapter 2, “Programming 
Considerations.” The workstation program attempts to suspend the 
previously active application. 


Restrictions on the Use of Semaphores 
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The supervisor imposes the following restrictions on the use of semaphores. 
Failure to follow these guidelines on the use of semaphores could result in 
system failure. 


1. A task that owns a semaphore should avoid going into a dispatcher wait 
state. If a task that holds a resource semaphore representing a limited 
resource goes into a wait state, the performance of other tasks that 
need to access the same resource will be adversely affected. 


2. A task that has claimed a code serialization semaphore must release 
that code serialization semaphore itself. Resource semaphores may be 
released by any task, even if the task requesting the release is not the 
task that claimed the semaphore. 


3. If more than one semaphore is required to access a resource, access to 
the semaphores should follow a defined order. An orderly access 
scheme for semaphore allocation reduces the possibility of resource 
deadlock. For example, without ordered semaphore access rules, a task 
that owns a semaphore may try to claim another semaphore that is 
owned by a task running at a higher priority. If the task running at a 
higher priority tries to claim the semaphore owned by the task running 
at the lower priority, neither task’s request can be satisfied, causing 
both tasks to be in an infinite wait state (deadlock). 


Semaphore Management Services Your Application Program Can Use 
The semaphore management services provided by the API are: 
e Claim aSemaphore: Use this service to claim a specified semaphore. 


e Release a Semaphore: Use this service to release a specified 
semaphore. 


e Query aSemaphore: Use this service to determine whether a 
specified semaphore is claimed or free. 


These services are described in Chapter 18, “Coding Semaphore 
Management Services.” 


Logical Timer Management 


The logical timer management services allow your application program to 
control time-dependent events through the use of logical timers. 


The logical timers implemented by the workstation program use 18.2 timer 
ticks per second. Thus, to specify a logical timer interval of 1 second, you 
should specify a timer interval of 18, for a 2-second timer interval, you 
should specify a timer interval of 36, and so on. 


Note: Reprogramming the PC timer on non-3270 PC systems could cause a 
host communication failure. 
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Logical Timer Management Services Your Application Program Can Use 


The logical timer management services provided by the API are: 


Get Logical Timer: Use this service to get a logical timer for the 
specified task. 


Set Logical Timer. Use this service to set the timer interval for a 
specified logical timer. 


Release Logical Timer: Use this service to release a logical timer. 


These services are described in Chapter 19, “Coding Logical Timer 
Management Services.” 


Fixed-Length Queue Management 


The fixed-length queue management services allow your application 
program to pass data to other tasks or components, and to receive data from 
other tasks or components, using the fixed-length queue as a “pipeline” for 
the data. 


Fixed-Length Queue Management Services Your Application Program Can 


Use 


The fixed-length queue management services provided by the API are: 


Enqueue Data: Use this service to enqueue data on the specified 
fixed-length queue. 


Dequeue Data: Use this service to dequeue data from the specified 
fixed-length queue. 


Purge Queue Data: Use this service to remove all data from the 
specified fixed-length queue. 


These services are described in Chapter 20, “Coding Fixed-Length Queue 
Management Services.” 


Interrupt Handler Management 


Interrupt handlers are code that performs immediate functions. There are 
two types of interrupt handlers: hardware and software. 
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Hardware Interrupt Handlers 


Hardware interrupt handlers generally perform action required to service a 
condition detected by the hardware. For example, a communication adapter 
may interrupt every time a character is received from the communication 
line. The interrupt handler would read the character received and perform 
any action required to allow the adapter to receive another character. 


There are three ways for your application program to take over hardware 
interrupts. The first way is to use the DOS function calls X‘35’ and X‘25’, 
described in the DOS Technical Reference manual. The second way is to 
use the Install a Hardware Interrupt Handler service provided by the 
supervisor. The third way is to use the Install an Interrupt Handler 
service. 


Using the DOS Function Calls to Take Over Hardware Interrupts 


A program may use the DOS facilities to take over a hardware interrupt, 
provided there is no requirement to share the interrupt with a program in 
another environment. The interrupt handler cannot be removed (short of a 
system re-IPL) without endangering the integrity of the system. 


Using the Install a Hardware Interrupt Handler Service to Take Over Hardware Interrupts 


The Install a Hardware Interrupt Handler service allows system extensions 
or applications requiring hardware interrupt service to install an interrupt 
handler in the system, and to share hardware interrupt vectors in certain 
circumstances. This service provides enough information for the supervisor 
to remove the interrupt handler without disturbing other users of that level 
if the environment is stopped. 


Programs that use the Install a Hardware Interrupt Handler service to 
share an interrupt vector must meet these restrictions: 


e The device must be pollable at one address, where the byte of data will 
return nonzero when it is logically ANDed with a byte mask whenever 


the device is interrupting. 


e It must be possible to disable the device by writing one byte of data toa 
single port address. 


e The handler should return with the FAR option (not IRET) and should 
not call the previous handler. 
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Using the Install an Interrupt Handler Service to Take Over Hardware Interrupts 


The Install an Interrupt Handler service allows system extensions or 
applications requiring hardware interrupt service to install an interrupt 
handler into the system. Using this service does not provide the supervisor 
with enough information to remove the interrupt handler without 
disturbing other users of that level if the environment is stopped. 
Therefore, use this service only if you cannot meet the restrictions for 
using the Install a Hardware Interrupt Handler service. Also, if a hardware 
interrupt handler installed by this service chooses to chain to the previous 
handler, it is imperative, before jumping to the previous handler, that the 
registers and stack be the same as when the interrupt handler gained 
control. 


Hardware Interrupt Handler Considerations 


Regardless of whether the application uses the DOS function calls or a 
supervisor service, no interrupt handler should ever create or destroy 
supervisory objects (such as gates, tasks, timers, or other interrupt 
handlers). Neither should a hardware interrupt handler attempt to use the 
Name Resolution service for supervisory objects. 


Note: Application programs should not take over a hardware interrupt by 
writing directly to the interrupt vector table. The workstation 
program will support programs that do this, but only with significant 
performance degradation. See Chapter 2, “Programming 
Considerations,” for more information. 


Software Interrupt Handlers 


Software interrupt handlers provide another means by which programs that 
are not linked together can communicate. One program can set an 
interrupt vector to point to a software interrupt handler within itself. 
When another program issues an INT instruction, the interrupt handler 
gains control. A software interrupt handler may be classified as either 
local or global. Local interrupt handlers may only receive interrupts 
originating within the same environment as the interrupt handler. Global 
interrupt handlers may receive interrupts originating from any 
environment. 


There are two ways for your application program to take over software 

interrupts. The first way is to use the DOS function calls X‘35’ and X‘25’, 
_ described in the DOS Technical Reference manual. The second way is to 

use the Install an Interrupt Handler service provided by the supervisor. 


Using the DOS Function Calls to Take Over Software Interrupts 
A program may use the DOS facilities to take over a software interrupt, 
provided there is no requirement to share the interrupt with a program in 


another environment. The interrupt handler will only gain control if the 
INT instruction is executed from within the same environment. 
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Using the Install an Interrupt Handler Service to Take Over Software Interrupts 


The supervisor provides a full set of interrupt vectors for each environment. 
When a software interrupt occurs, the supervisor fields the interrupt, uses 
its system’s tables to determine the active environment, and gives control to 
the appropriate software interrupt handler. The Install an Interrupt 
Handler service allows programs to request that a software interrupt 
handler be installed. This service allows interrupt handlers to be defined as 
“local” or “global.” 


Local Software Interrupt Handlers 


Local interrupt handlers only receive software interrupts on the requested 
vector when the interrupt originated in the handler’s own environment. 


Global Software Interrupt Handlers 


Global interrupt handlers receive all software interrupts for a given vector, 
regardless of the environment that issued it. 


An additional option for global software interrupt handlers is available. A 
program may request to service software interrupts as a “last resort.” The 
requester will get the interrupt only if no other interrupt handlers are 
found to service it. 


Generally, programs should avoid the use of global interrupt handlers if the 
purpose of the interrupt handler is to provide some service to other 
programs, since program environments can be stopped, killed, or suspended 
at any time during the software interrupt processing. To avoid this 
problem, the program should be written as a system extension and define 
gates, components, or tasks in order to receive requests. Another 
possibility is to have the interrupt handler claim a code serialization 
semaphore before processing the interrupt. Tasks holding code 
serialization semaphores are not stopped until the semaphore is released. 


Note: Global or last-resort interrupt handlers cannot be installed in a 
stoppable environment. 


Software Interrupt Handler Considerations 
Application programs should not take over a software interrupt by writing 
directly to the interrupt vector table. The workstation program supports 


programs that do this, but only with significant performance degradation. 
See Chapter 2, “Programming Considerations,” for more information. 
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Interrupt Handler Management Services Your Application Program Can Use 


14-20 


The interrupt handler management services provided by the API are: 


Install a Hardware Interrupt Handler: Use this service to identify 
an interrupt routine that is to gain control on hardware interrupts. 


Install an Interrupt Handler: Use this service to identify an 
interrupt routine that is to gain control on software or hardware 
interrupts. This service also returns the entry point of the previous 
interrupt handler. For hardware interrupt handlers, the Install a 
Hardware Interrupt Handler service is the recommended service to use 
if you can satisfy the restrictions for using it. 


Query Interrupt Vector Contents: Use this service to obtain the 
entry point address of the second-level interrupt handler currently 
installed for the specified interrupt vector. 


Remove an Interrupt Handler: Use this service to remove an 
interrupt handler that was installed through the Install a Hardware 
Interrupt Handler or Install an Interrupt Handler service request. 


These services are described in Chapter 21, “Coding Interrupt Handler 
Management Services.” 
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Introduction 


Introduction 
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This chapter describes how to code requests for the supervisory object 
services provided by the API. 


The supervisory object services allow your application program to create 
and delete tasks, components, semaphores, fixed-length queues, gates, and 
user exit tables. The supervisory object services also allow your 
application program to obtain the numeric ID of a supervisory object by 
specifying its alphanumeric name, or obtain the alphanumeric name of the 
supervisory object by specifying its numeric ID. 


The supervisory object services provided by the API are: 


Create a Task Entry: Use this service to create an entry in the SVC 
table for a task. 


Create a Component Entry: Use this service to create an entry in 
the SVC table for a component. 


Create a Semaphore Entry: Use this service to create an entry in 
the SVC table for a semaphore. 


Create a Fixed-Length Queue Entry: Use this service to create an 
entry in the SVC table for a fixed-length queue. 


Create a Gate Entry: Use this service to create an entry in the SVC 
table for a gate. 


Create a User Exit Table Entry: Use this service to create an entry 
in the SVC table for a user exit table. 


Install User Exit Table Entries: Use this service to install entries 
in the specified user exit table. 


Name Resolution: Use this service to resolve the specified 
supervisory object name to its numeric index. 


ID Resolution: Use this service to resolve the specified supervisory 
ID name to its alphanumeric name. 


Delete an Entry: Use this service to delete an entry in the SVC table 
representing the specified supervisory object. 


When created, an object can be optionally named. That name, however, 
must be unique. 


Introduction 


Note: Following is a list of names used by the supervisor. Do not assign 
these same names to system objects that you create. 


Names that begin with the letters IND or 8270KS 
SYSKILL 
MEMORY 
DOSINT21 
DOSIOR 
DOSBADP 
XLATE 
SESSMGR 
KEYBOARD 
WSCTRL 
OIAM 
CPYUET 
MFIC 
38270EML 
PCPSM 
COPY 
BSMUET 


Requesting the Supervisory Object Services 


To request any of the supervisory object services, load the registers and the 
parameter list with the proper values, and use the INT 7AH instruction to 
signal the workstation program that it has a request to process. 


Return Codes for the Supervisory Object Services 


Return codes for the supervisory object services are 2-byte values made up 
of a function ID and an error code. The function ID indicates the portion of 
the workstation program in which the error occurred. The error code 
indicates the specific type of error that has occurred. An error code of 
X‘00’ indicates a successful acceptance or completion of the request. 


After your application has requested a supervisory object service, the CH 
and CL registers contain a return code generated by the request processing 
portion of the workstation program. The function ID is in the CH register, 
and the error number is in the CL register. The return codes that can be 
generated by supervisory object services are called system return codes. The 
function ID for system return codes is X‘12’ or X‘13’. The error codes that 
can appear are specific to the service that was requested and are included 
in the descriptions of each service. 


See Appendix H, “Return Codes,” for more information. 
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Create Task Entry 


Supervisory Object Service X‘92’: Create Task Entry 


Register Values 


Use this service to create an entry in the SVC table for a task. 


On 


AH 
AL 
BH 
BL 
CX 
DX 
ES 
DI 


Request On Completion 
= X‘92’ CH = Function ID 
= X‘00’ CL = Return code 
= Preemptive status DX = Task ID 
= 00 = no name / 01 = name / 02 = reset 
= Task priority The contents of registers 
= Task ID * AX, BX, ES, and DI are 
= Segment address of the parameter list unpredictable. 
= Offset address of the parameter list 


* The value coded in the DX register is dependent on the value coded in 
the BL register. See “Register Definitions” below for more information. 


Register Definitions 
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Request Registers: 


The BH register indicates whether the new task is preemptable. 
Possible values for the BH register are : 


X‘00’ = The task is preemptable. 
X‘01’ = The task is nonpreemptable within its priority level. 
X‘02’ = The task is nonpreemptable within its environment. 


If the BH register contains a value other than X‘00’, X‘01’, or X‘02’, the 
supervisor sets the preemptive status of the task to “preemptable.” 


The BL register indicates whether the task has a name associated with 
it, or whether the task is to be reinitialized with the specified 
parameters. 


Possible values for the BL register are : 
X‘00’ = The task has no name. 


X‘01’ = The task’s name is in the parameter list. 
X‘02’ = The task is to be reset to the specified parameters. 


The “reset” option can only be used by requesters resetting tasks within | 
the same environment. It is used for tasks previously created and still 
in the system. Use this option if you want to reinitialize the task. You 
must include all input as if you were creating the task for the first time. 
This option should only be used after a stop environment service that 
also used the reset option. 


Create Task Entry 


e The CX register indicates the dispatch priority of the task. If a system 
extension is issuing this request, valid dispatch priorities are 1 through 
64. If an application program running in a stoppable environment is 
issuing this request, valid dispatch priorities are 36 through 64. 

e The DX register indicates the task ID of the task to be reset. This 
register is used only if the BL register indicates that the task is to be 
reset. 

e The ES register contains the segment address of the parameter list. 

e The DI register contains the offset address of the parameter list. 


Completion Registers: 


e The DX register contains the ID of the task. 


Parameter List Format 


Contents Contents 
Offset Length on Request on Completion 
1 word Offset address of Unchanged 
the task’s stack 


2 1 word Segment address Unchanged 
of the task’s stack 


S bytes Unchanged 


Parameter Definitions 
Request Parameters: 


e The offset specified for the stack must point to the address containing 
the initial ES register value, so the stack should be set up as follows: 


SP ——»> Initial ES register contents Low end of stack 
Initial DS register contents 
Initial SI register contents 
Initial DI register contents 
Initial BP register contents 
Initial DX register contents 
Initial CX register contents 
Initial BX register contents 
Initial AX register contents 
Initial IP register contents 
Initial CS register contents 


Initial flag register High end of stack 


Note: When a task is dispatched, all the initial register values are 


placed into the corresponding registers and an IRET instruction 
is performed. 
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Create Task Entry 


Return Codes 


Usage Notes 
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Note: When a task is dispatched, all the initial register values are 
placed into the corresponding registers and an IRET instruction 
is performed. 


e The task name is an optional parameter and is needed only if the BL 
register is set to 1 on request. The task name can be a maximum of 
eight ASCII characters and should be padded to the right with blanks if 
it is less than eight characters. 


The CH and CL registers contain a return code generated by the 
workstation program. System return codes use a function ID of X‘12’ or 
X‘13’ (found in the CH register). The error codes that can be received are: 


Code Meaning 


X‘00° Successful completion of the request. 
X‘01’ The task name already exists. 

X‘02’ SVC table full. 

X ‘03’ Name table full. 

X‘04’ No more free TCBs. 

X ‘05’ Invalid task ID (on reset). 

X‘06’ Invalid priority. 


e A task is always created in the “unready” state. You must set the task 
to the “ready” state to make it dispatchable. 


e A task is a continually executing thread. Therefore, care must be taken 
when it completes its function. In a stoppable environment, the only 
task that should return to DOS is the task under which the application 
first began running. All other tasks should be deleted. In a 
nonstoppable environment, most tasks will be in never-ending 
loops—typically, waiting for a unit of work, performing that work, and 
looping to the top, where it will wait again for the next unit of work. 


e Whenever a task or component is providing a service to other 
applications, and a parameter list is required, the first two bytes of the 
parameter list should be used as the return code field. 


Coding Example 


. 
, 


° 
’ 


CTTASKSP 


DW 0 
CTTASKSS DW 0 
CTTSKNAM 


e 
, 


. 
f 


PARAMETER LIST FOR CREATE TASK 


° 
, 


° 
’ 


DB 8 DUP(O) : 


THE TASK'S STACK 


STACK DB 


ry 
f 
. 
f 


. 
1 


v 


, 


f 


256 DUP (0) 


INITIALIZE THE TASK'S STACK 


PUSH 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
POP 
PUSH 
MOV 
POP 


DS ; 
AX,SEG STACK : 
DS , AX 

SI,OFFSET STACK . 


Create Task Entry 


TASK'S STARTING SP 
TASK'S STARTING SS 
TASK NAME 


SAVE DS 
GET THE TASK'S STACK SEGMENT 


DS:SI NOW POINT TO THE TASK STACK 


WORD PTR [SI+254],0F242H ; SET FLAGS IN THE STACK 


AX,SEG TASK 

WORD PTR [SI+252] ,AX 
AX,OFFSET TASK 

WORD PTR [SI+250] ,AX 
AX 

AS 

WORD PTR [SI+234],AX 
DS : 


; SET CODE SEGMENT OF TASK IN STACK 


SET CODE OFFSET OF TASK IN STACK 
GET THE PROGRAM'S DS REGISTER INTO 
AX (PUT IT BACK ON THE STACK) 

; SET DATA SEGMENT IN STACK 

RESTORE DS 


eo Ne Ne Me 


INITIALIZE PARAMETER LIST FOR CREATE TASK 


MOV 
ADD 


MOV 
MOV 
MOV 


MOV 


AX,OFFSET STACK 
AX,232 


CTTASKSP , AX 
AX,SEG STACK 
CTTASKSS , AX 


A at et ee eT) 


BL,O ; 


GET THE OFFSET OF THE TASK'S STACK 
INCREMENT THE SP TO POINT AT THE 
START OF REGISTER RESTORE AREA 
PUT TASK'S SP IN PARAMETER LIST 
PUT TASK'S SS IN PARAMETER LIST 


NO NAME SPECIFIED 


INITIALIZE REGISTERS FOR CREATE TASK 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


AH , 92H 

AL,O 

BH, PREEMPT ; 
CX, PRIORITY ; 
DI, SEG CTTASKSP ; 
ES,DI ; 
DI,OFFSET CTTASKSP ; 


PREEMPTION TYPE IN BH 

PRIORITY IN CX 

SEGMENT ADDRESS OF PARAMETER LIST 
IN ES 

OFFSET OF PARAMETER LIST IN DI 


SIGNAL WORKSTATION PROGRAM FOR CREATE TASK SERVICE 


INT 


7AH 
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Create Component Entry 


Supervisory Object Service X‘93’: Create Component 
Entry 


Use this service to create an entry in the SVC table for a component. 


Register Values 


On Request On Completion 
AH X‘93’ CH = Function ID 
AL X‘00’ CL Return code 


ll 


BL = 00 = no name / 01 = name DX Component ID 

ES = Segment address of the parameter list 

DI = Offset address of the parameter list The contents of registers 
AX, BX, ES, and DI are 
unpredictable. 


Register Definitions 
Request Registers: 


'@ The BL register indicates whether the component has a name associated 
with it. 


Possible values for the BL register are : 


X‘00’ = The component has no name. 
X‘01’ = The component’s name is in the parameter list. 


e The ES register contains the segment address of the parameter list. 
e The DI register contains the offset address of the parameter list. 
Completion Registers: 


e The DX register contains the ID of the component. 


15-8 


Create Component Entry 


Parameter List Format 


Contents Contents 
Offset Length on Request on Completion 
1 word Offset address of Unchanged 
the component’s 
2 1 word Unchanged 
component’s entry 
point 


entry point 
8 bytes Unchanged 


Segment address 
of the 


Parameter Definitions 


Return Codes 


Usage Notes 


Request Parameters: 


e The entry point of the component is specified as the contents of the CS 
and IP registers when the component is invoked. 


e The component name is an optional parameter and is needed only if the 
BL register is set to 1 on request. The component name can be a 
maximum of eight ASCII characters and should be padded to the right 
with blanks if necessary. 


The CH and CL registers contain a return code generated by the 
workstation program. System return codes use a function ID of X‘12’ or 
X‘13’ (found in the CH register). The system return codes that can be 
received for this service are: 


Code Meaning 
X‘00’ Successful completion of the request. 
X‘01’ The component name already exists. 


X ‘02’ SVC table full. 
X‘03’ Name table full. 


e When a component receives control, the pointer to the parameter list 
will be in the ES and DI registers. 


e When a component receives control, interrupts are disabled. 


e When a component is finished executing, it should use a RETURN FAR 
to return. 
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Create Component Entry 


Coding Example 


° 
, 


; PARAMETER LIST FOR CREATE A COMPONENT 


CCCMPOFF DW 0 
CCCMPSEG DW 0 
8 DUP(0) 


CCNAME 


. 
V 


DB 


e 
’ 
. 
f 


. 
, 


COMPONENT ENTRY POINT OFFSET 
COMPONENT ENTRY POINT SEGMENT 
COMPONENT NAME 


; INITIALIZE PARAMETER LIST FOR CREATE A COMPONENT 


° 
r 


MOV 
MOV 
MOV 
MOV 


MOV 
MOV 
MOV 
MOV 
MOV 
REP 


AX,OFFSET CMPONENT 
CCCMPOFF , AX 

AX,SEG CMPONENT 
CCCMPSEG , AX 


AX,SEG CCNAME 
ES ,AX 

DI,OFFSET CCNAME 
SI,OFFSET COMPNAME 
CX, 8 

MOVSB 


° 
i 


° 
’ 


° 
f 


. 
, 
. 
f 


. 
i 


COMPONENT OFFSET INTO THE LIST 

COMPONENT SEGMENT INTO THE LIST 

[ES:DI] POINTS TO THE DESTINATION IN THE 
PARAMETER LIST 

[DS:SI] POINTS TO SOURCE OF THE NAME 


MOVE 8 BYTES 
COPY THE NAME INTO THE PARM LIST 


; INITIALIZE REGISTERS FOR CREATE A COMPONENT 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


AH, 93H 

AL,O 

BL,1 

DI, SEG CCCMPOFF 
ES,DI 

DI,OFFSET CCCMPOFF 


° 
i 
e 
f 
° 
f 
. 
f 


BL = 1 SINCE A NAME IS SPECIFIED 

SEGMENT ADDRESS OF PARAMETER LIST 
IN ES 

OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR CREATE A COMPONENT SERVICE 
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INT 


7AH 


Create Semaphore Entry 


Supervisory Object Service X‘94’: Create Semaphore 


Entry 


Use this service to create an entry in the SVC table for a semaphore. 


Register Values 


On 


Register Definitions 


Request On Completion 

= ‘94’ CH = Function ID 

= Semaphore type CL = Return code 

= 00 = no name / 01 = name DX = Semaphore ID 

= Segment address of the parameter list 

= Offset address of the parameter list The contents of registers 
AX, BX, ES, and DI are 
unpredictable. 


Request Registers: 


The BH register indicates the semaphore type. 
Possible values for the BH register are : 


X‘03’ = The semaphore is a code serialization semaphore. 
X‘04’ = The semaphore is a resource semaphore. 


See Chapter 14, “Supervisor Services,” and Chapter 2, “Programming 
Considerations,” for guidelines on using semaphores. 


The BL register indicates whether the semaphore has a name associated 
with it. 


Possible values for the BL register are : 


X‘00’ = The semaphore has no name. 
X‘01’ = The semaphore’s name is in the parameter list. 


The ES register contains the segment address of the parameter list. 
The DI register contains the offset address of the parameter list. 


Note: The parameter list is needed only if the BL register is set to 1. 


Completion Registers: 


The DX register contains the ID of the semaphore. 
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Create Semaphore Entry 


Parameter List Format 


Contents Contents 
Offset Length on Request on Completion 


Unchanged 


Parameter Definitions 


Return Codes 


15-12 


Request Parameters: 


The semaphore name is an optional parameter and is needed only if the BL 
register is set to 1 on request. The semaphore name can be a maximum of 
eight ASCII characters and should be padded to the right with blanks if 
necessary. 


The CH and CL registers contain a return code generated by the 
workstation program. System return codes use a function ID of X‘12’ or 
X‘13’ (found in the CH register). The error codes that can be received are: 


Code Meaning 


X ‘00’ Successful completion of the request. 
X‘01’ The semaphore name already exists. 
X ‘02’ SVC table full. 

X ‘03’ Name table full. 


— XC’ Invalid semaphore type. 


Coding Example 


* 
‘ 


Create Semaphore Entry 


; PARAMETER LIST FOR CREATE A SEMAPHORE ENTRY 


CSNAME DB 8 DUP(0O) 


’ 


SEMAPHORE NAME 


; INITIALIZE PARAMETER LIST FOR CREATE A SEMAPHORE ENTRY 


MOV 
MOV 
MOV 
MOV 
MOV 
REP 


ST,OFFSET SEMNAME 
AX,SEG CSNAME 
ES , AX 

DI,OFFSET CSNAME 
CX ,8 

MOVSB 


[DS:SI] POINTS TO SOURCE OF THE NAME 
[ES:DI] POINTS TO DESTINATION IN PARM 
LIST 


MOVE 8 BYTES 
COPY THE NAME INTO THE PARM LIST 


; INITIALIZE REGISTERS FOR CREATE A SEMAPHORE ENTRY 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


AH, 94H 

BH, 03H 

Biss i 

DI, SEG CSNAME 
ES ,DI 

DI,OFFSET CSNAME 


me NO Ne Ne Ne 


SEMAPHORE TYPE = CODE SERIALIZATION 

BL = 1 SINCE A NAME IS SPECIFIED 

SEGMENT ADDRESS OF PARAMETER LIST 
IN ES 

OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR CREATE A SEMAPHORE ENTRY SERVICE 


INT 


7AH 
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Create Fixed-Length Queue Entry 


Supervisory Object Service X‘04’: Create Fixed-Length 


Queue Entry 


Use this service to create an entry in the SVC table for a fixed-length 


queue. 
Register Values 


On Request 


AH X‘04’ 

BL = 00 = no name/ 01 = name 

CX = Queue length 

ES Segment address of the parameter list 
DI Offset address of the parameter list 


I 


lott | 


Register Definitions 


Request Registers: 


On Completion 


CH = Function ID 
CL = Return code 
DX = Queue ID 


The contents of registers 
AX, BX, ES, and DI are 
unpredictable. 


e The BL register indicates whether the queue has a name associated 


with it. 
Possible values for the BL register are: 


X‘00’ = The queue has no name. 


X‘01’ = The queue’s name is in the parameter list. 


e The CX register contains the number of bytes your application program 
has reserved for the fixed-length queue. The queue must be greater 
than 10 bytes long, because the first 10 bytes of the queue are reserved 


for use by the workstation program. 


e The ES register contains the segment address of the parameter list. 


e The DI register contains the offset address of the parameter list. 


Completion Registers: 


e The DX register contains the ID of the fixed-length queue. 


15-14 


Parameter List Format 


Create Fixed-Length Queue Entry 


Contents Contents 
Offset Length on Request on Completion 


Offset address of Unchanged 
the queue 


2 1 word Segment address Unchanged 
of the queue 


Parameter Definitions 


Return Codes 


Usage Notes 


Unchanged 


Request Parameters: 


The queue name is an optional parameter and is needed only if the BL 
register is set to 1 on request. The queue name can be a maximum of eight 
ASCII characters and should be padded to the right with blanks if 


necessary. 


The CH and CL registers contain a return code generated by the 
workstation program. System return codes use a function ID of X‘12’ or 
X‘13’ (found in the CH register). The error codes that can be received are: 


Code 


X‘00’ 
X‘01’ 
X‘02’ 
X ‘03’ 
X‘41’ 


Meaning 


Successful completion of the request. 
The queue name already exists. 

SVC table full. 

Name table full. 

Invalid queue length. 


The fixed-length queue resides in the requester’s environment. 
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Create Fixed-Length Queue Entry 


Coding Example 


15-16 


° 
? 


° 
‘ 


DEFINE PARAMETER LIST FOR CREATE QUEUE 


COQOFFS DW 
COSEGM DW 
COQNAME DB 


~e Se Ne 


f 


e 
f 


° 
f 


0 
0 
8 DUP(' ') 


INITIALIZE FIRST 2 ENTRIES OF PARAMETER LIST 


MOV 
MOV 


MOV 
CLD 
MOV 
MOV 
MOV 
REP 


CQQOFFS,OFFSET Q 
CQOSEGM,SEG Q ; 


=e 


THE USER HAS A QUEUE NAME 


BL,0O1H 


CX,4 
SI,OFFSET QNAME ; 


OFFSET OF QUEUE 
SEGMENT OF QUEUE 


INDICATE A QNAME IS SPECIFIED 

BEGIN MOVING QNAME TO THE PARAM LIST 
QONAME IS FOUR WORDS LONG 

SOURCE OFFSET OF QUEUE 


DI,OFFSET CQQNAME;DESTINATION OFFSET IS CQQNAME 


MOVSW ; 


MOVE QNAME TO PARAMETER LIST 


INITIALIZE REGISTERS FOR CREATE QUEUE 


MOV 
MOV 
MOV 
MOV 
MOV 


AH, 04H 

Cx, 50 

DI,SEG CQQOFFS 
ES ,DI 
DI,OFFSET CQQOFFS; 


e me Ne Ne 


CX = NUMBER OF BYTES FOR QUEUE 
ADDRESSABILITY TO 

PARAMETER LIST 

USING ES:DI 


SIGNAL WORKSTATION PROGRAM FOR CREATE QUEUE SERVICE 


INT 


7AH 


Create Gate Entry 


Supervisory Object Service X‘9A’: Create Gate Entry 


Use this service to create an entry in the SVC table for a gate. 


Register Values 


On Request On Completion 

AH = X‘9A’ CH = Function ID 

BL = 00 = no name / 01 = name CL = Return code 

CX = Number of services DX = Gate ID 

ES = Segment address of the parameter list 

DI = Offset address of the parameter list The contents of registers 
AX, BX, ES, and DI are 
unpredictable. 


Register Definitions 
Request Registers: 


e The BL register indicates whether the gate has a name associated with 
it. 


Possible values for the BL register are : 


X‘00’ = The gate has no name. 
X‘01’ = The gate’s name is in the parameter list. 


e The CX register indicates the number of services provided by the gate. 
e The ES register contains the segment address of the parameter list. 

e The DI register contains the offset address of the parameter list. 
Completion Registers: 


e The DX register contains the ID of the gate. 
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Create Gate Entry 


Parameter List Format 


Contents Contents 
Offset Length on Request on Completion 


1 word Offset address of Unchanged 
the service entry 
array 
1 word Segment address Unchanged 


of the service 
entry array 


e bytes Unchanged 


Parameter Definitions 


15-18 


Request Parameters: 


e The format of the service entry array is as follows: 


a 
Offset Length on Request on Completion 
fo [word | Service entry [Unchanged 


Service entry n, where Unchanged 
n is the number of 
service entries 

specified in the CX 


register on request. 


A service entry is the ID of the task or component that will provide the 
service. This ID was obtained when the task or component was created. 


e The gate name is an optional parameter. The gate name can be a 
maximum of eight ASCII characters and should be padded to the right 
with blanks if necessary. 


Return Codes 


Usage Notes 


Create Gate Entry 


The CH and CL registers contain a return code generated by the 
workstation program. System return codes use a function ID of X‘12’ or 
X‘13’ (found in the CH register). The error codes that can be received are: 


Code 


X‘00’ 
X‘01’ 
X‘02’ 
X‘03’ 
X‘OF’ 
X‘34’ 


X‘3B’ 


Meaning 


Successful completion of the request. 

The gate name already exists. 

SVC table full. 

Name table full. 

Invalid environment access. 

The service entry is not a task or component ID, or the number 
of services specified in the gate is invalid. 

Gate table full. 


e Only nonstoppable environments (system extensions) can create gates. 


e Service entries may not be changed, added to, or deleted from a gate 
after it has been initialized. 


e Requests through gates can be made from any environment. 
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Create Gate Entry 


Coding Example 


15-20 


° 
/ 


° 
f 


PARAMETER LIST FOR CREATE A GATE 


CGENTRYS DD NTRYARAY 


CGNAME 


. 
, 


° 
, 


ENTRY ARRAY 


NTRYARAY DW 


e 
f 


° 
, 


ua Ne tO 


, 


DB 8 DUP(0) ; 


10 DUP(O) ; 


ENTRY 


POINTER TO ENTRY ARRAY 
GATE NAME 


ENTRY ARRAY FOR 10 ENTRIES 


INITIALIZE PARAMETER LIST FOR CREATE A GATE ENTRY 


MOV 
MOV 
MOV 
MOV 
MOV 
REP 


AX,SEG CGNAME ; 
ES , AX ; 
DI,OFFSET CGNAME 

SI,OFFSET GATENAME ; 
CxX,8 ; 
MOVSB ; 


ES:DI POINT TO DESTINATION IN PARM 
LIST 


DS:SI POINT TO SOURCE OF THE NAME 
MOVE 8 BYTES 
COPY THE NAME INTO THE PARM LIST 


INITIALIZE REGISTERS FOR CREATE A GATE ENTRY 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


AH , 9AH 

Buy ; 
CX,10 7 
DI, SEG CGENTRYS 7 
ES,DI - 
DI,OFFSET CGENTRYS ; 


BL = 1 SINCE A NAME IS SPECIFIED 

CX = NUMBER OF ENTRIES (10) 

SEGMENT ADDRESS OF PARAMETER LIST 
IN ES 

OFFSET OF PARAMETER LIST IN DI 


SIGNAL WORKSTATION PROGRAM FOR CREATE A GATE ENTRY SERVICE 


INT 


7AH 


Create User Exit Table Entry 


Supervisory Object Service X‘97’: Create User Exit Table 
Entry 


Use this service to create an entry in the SVC table for a user exit table. 


Register Values 


On Request On Completion 

AH = X‘97’ CH = Function ID 

BL = 00 = no name / 01 = name CL = Return code 

CX = Number of entries DX = User exit table ID 

ES = Segment address of the parameter list 

DI = Offset address of the parameter list The contents of registers 
AX, BX, ES, and DI are 
unpredictable. 


Register Definitions 
Request Registers: 


e The BL register indicates whether the user exit table has a name 
associated with it. 


Possible values for the BL register are : 


X‘00’ = The user exit table has no name. 
X‘01’ = The user exit table’s name is in the parameter list. 


e The CX register contains the maximum number of entries that the user 
exit table will be able to contain. 


e The ES register contains the segment address of the parameter list. 
e The DI register contains the offset address of the parameter list. 
Completion Register: 


e The DX register contains the ID of the user exit table. 
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Create User Exit Table Entry 


Parameter List Format 


Contents Contents 
Offset Length on Request on Completion 
1 word Offset address of Unchanged 
the user exit table 
2 1 word Segment address Unchanged 
of the user exit 
table 
4-11 8 bytes User exit table Unchanged 
name 


Parameter Definitions 
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Request Parameters: 


e The format of the user exit table is as follows: 


Offset address of user exit table entry 0 


Offset address of user exit table entry 1 


eee Segment address of user exit table entry 


18st word Offset address of user exit table entry 2 


1 
Segment address of user exit table entry 
2 


Offset address of user exit table entry 3 


Segment address of user exit table entry 
3 


Offset address of user exit table entry 
n-l 
An-2 Segment address of user exit table entry 
n-1 


In this table, n is the number of entries in the user exit table. User exit 
table entries are numbered from 0 to n-1. The contents of a user exit 
entry are the address of code to be given control when it is invoked by 
means of a CALL FAR instruction. 


e The user exit table name is an optional parameter. The user exit table 
name can be a maximum of eight ASCII characters and should be 
padded to the right with blanks if necessary. 


Return Codes 


Usage Notes 


Create User Exit Table Entry 


The CH and CL registers contain a return code generated by the 
workstation program. System return codes use a function ID of X‘12’ or 
X‘13’ (found in the CH register). The error codes that can be received are: 


Code Meaning 


X‘00’ Successful completion of the request. 
X‘01’ The name already exists. 

X‘02’ SVC table full. 

X‘03’ Name table full. 

X‘35’ The user exit table size cannot be zero. 


e Access to user exit tables is not valid between stoppable environments. 


Coding Example 


° 
v 


° 
uy 


CUUETOFF DW 0 
CUUETSEG DW 0 
CUNAME 


° 
, 


° 
f 


PARAMETER LIST FOR CREATE A USER 


DB 8 DUP(0O) ; 


USER EXIT TABLE 


UET DD 


, 


Ul 


t 


7 DUP(?) ; 


EXIT TABLE ENTRY 


OFFSET OF USER EXIT TABLE 
SEGMENT OF USER EXIT TABLE 
USER EXIT TABLE NAME 


THE USER EXIT TABLE 


INITIALIZE PARAMETER LIST FOR CREATE A USER EXIT TABLE ENTRY 


MOV 
MOV 
MOV 
MOV 


AX,OFFSET UET ; 
CUUETOFF , AX 
AX,SEG UET ; 
CUUETSEG , AX 


OFFSET OF USER EXIT TABLE INTO THE LIST 


SEGMENT OF USER EXIT TABLE INTO THE LIST 


INITIALIZE REGISTERS FOR CREATE A USER EXIT TABLE ENTRY 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


AH,97H 

BL,O ; 
CX,7 ; 
DI, SEG CUUETOFF ; 
ES,DI ; 
DI,OFFSET CUUETOFF ; 


BL = 0 SINCE NO NAME IS SPECIFIED 
NUMBER OF ENTRIES IN USER EXIT TABLE = 7 
SEGMENT ADDRESS OF PARAMETER LIST 

IN ES 
OFFSET OF PARAMETER LIST IN DI 


SIGNAL WORKSTATION PROGRAM FOR CREATE A USER EXIT TABLE ENTRY SERVICE 


INT 


TAH 
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Install User Exit Table Entries 


Supervisory Object Service X‘0E’: Install User Exit Table 


Entries 


Register Values 


Use this service to install up to n entries in the specified user exit table. 


On Request On Completion 


AH X‘OE’ CH Function ID 


DX = User exit table ID CL Return code 
ES = Segment address of the parameter list 
DI = Offset address of the parameter list The contents of registers 


AX, BX, DX, ES, and DI 
are unpredictable. 


Register Definitions 


Request Registers: 


e The DX register contains the ID of the user exit table where the entries 
are to be installed. 

e The ES register contains the segment address of the parameter list. 

e The DI register contains the offset address of the parameter list. 


Parameter List Format 


15-24 


Contents Contents 
Offset | Length on Request on Completion 
1 word n (number of user exit table | Unchanged 
entries) 
2 1 word User exit table entry Unchanged 
number 


Offset address of user exit 


1 word Segment address of user Previous contents 
exit 
6n-4 | 1 word User exit table entry Unchanged 
number 


[en [aword | Ottset address of usor exit 


exit 


Install User Exit Table Entries 


Parameter Definitions 


Return Codes 


Usage Notes 


Request Parameters: 


e The format of the user exit table is as follows: 


fo |aword | Oftset adios of user exit entay 0 
[é__]iword | Segment address of user exit entey 1 
fs ]iword | Offset address of user exit entry 2 


Offset address of user exit entry n-1 
Segment address of user exit entry n-1l 


Where n is the number of entries in the user exit table. User exit table 
entries must start with entry 0 as the first entry. 


The CH and CL registers contain a return code generated by the 
workstation program. System return codes use a function ID of X‘12’ or 
X‘13’ (found in the CH register). The error codes that can be received are: 


Code Meaning 


X‘00’ Successful completion of the request. 

X‘05’ Invalid user exit table ID. 

X‘15’ The user exit table entry number is out of range. 

X‘16’ An incorrect number of user exit table entries was specified. 

X‘1A’  ~—s—- The user exit table address space is not available to the 
requester. 


This service may be requested between nonstoppable environments or 
within the requester’s environment. 
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Install User Exit Table Entries 


Coding Example 


. 
i 


; PARAMETER LIST FOR INSTALL USER EXIT TABLE ENTRIES 


IUNUMENT 
IUUET1NO 
IUUETIOF 
IUUET1SG 
IUUET2NO 
IUUET20F 
IUUET2SG 
IUUET3NO 
IUUET30F 
IUUET3SG 


° 
, 


DW 
DW 


oOO0C00CO0O0000 


i eT | eT TY 


NUMBER OF USER EXIT TABLE ENTRIES 
USER EXIT TABLE ENTRY NUMBER 
OFFSET OF USER EXIT TABLE ENTRY 
SEGMENT OF USER EXIT TABLE ENTRY 
USER EXIT TABLE ENTRY NUMBER 
OFFSET OF USER EXIT TABLE ENTRY 
SEGMENT OF USER EXIT TABLE ENTRY 
USER EXIT TABLE ENTRY NUMBER 
OFFSET OF USER EXIT TABLE ENTRY 
SEGMENT OF USER EXIT TABLE ENTRY 


; INITIALIZE PARAMETER LIST FOR INSTALL USER EXIT TABLE ENTRIES 


. 
a 


; INITIALIZE REGISTERS FOR INSTALL 


MOV 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


MOV 
MOV 
MOV 
MOV 
MOV 


IUNUMENT, 3 


AX, ENTLNO 

[BX]. IUNUMBER , AX 
AX,OFFSET ENT1 
[BX]. LUUETOFF ,AX 
AX,SEG ENT1 

[BX] . IUUETSEG , AX 


AX, ENT2NO 

[BX] . IUNUMBER ,AX 
AX,OFFSET ENT2 
[BX] . IUUETOFF , AX 
AX,SEG ENT2 

[BX] . IUUETSEG , AX 


AX , ENT3NO 

[BX] . IUNUMBER , AX 
AX,OFFSET ENT3 
[BX] . IUUETOFF , AX 
AX,SEG ENT3 
[BX]. IUUETSEG , AX 


AH, OFH 

DX, UETID 

DI, SEG IUNUMENT 
ES ,DI 


DI,OFFSET IUNUMENT 


=e 


=e 


=e 


3 ENTRIES TO INSTALL IN THE USER EXIT TABLE 


NUMBER OF THE 1ST ENTRY IN THE LIST 


OFFSET OF THE 1ST ENTRY IN THE LIST 


SEGMENT OF THE 1ST ENTRY IN THE LIST 


NUMBER OF THE 2ND ENTRY IN THE LIST 


OFFSET OF THE 2ND ENTRY IN THE LIST 


SEGMENT OF THE 2ND ENTRY IN THE LIST 


NUMBER OF THE 3RD ENTRY IN THE LIST 


OFFSET OF THE 3RD ENTRY IN THE LIST 


SEGMENT OF THE 3RD ENTRY IN THE LIST 


USER EXIT TABLE ENTRIES 


e 
f 
° 
f 
° 
Ud 
e 
, 


USER EXIT TABLE ID IN DX 

SEGMENT ADDRESS OF PARAMETER LIST 
IN ES 

OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR INSTALL USER EXIT TABLE ENTRIES SERVICE 
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INT 


7AH 


Name Resolution 


Supervisory Object Service X‘81’: Name Resolution 


Use this service to resolve the specified supervisory object name to its 
numeric index. 


Register Values 


On Request On Completion 


AH X81’ BH Object type 


ES = Segment address of the parameter list CH = Function ID 
DI = Offset address of the parameter list CL = Return code 
DX = Resolved name 


The contents of registers 
AX, BL, ES, and DI are 
unpredictable. 


Register Definitions 
Request Registers: 
e The ES register contains the segment address of the parameter list. 
e The DI register contains the offset address of the parameter list. 
Completion Registers: 


e The BH register indicates the type of the specified supervisory object. 
Possible supervisory object types are as follows: 


X‘00’ — Task 

X‘01’ — Component 

X‘03’ — Code serialization semaphore 
X‘04’ — Resource semaphore 

X‘05’ — Fixed-length queue 

X‘06’ — User exit table 

X‘07’ — Gate. 


e The DX register contains the supervisory object ID of the resolved 


name, which is the numeric representation of the alphanumeric 
supervisory object name. 
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Name Resolution 


Parameter List Format 


Contents Contents 
Offset Length on Request on Completion 
ae | 8 bytes Supervisory Unchanged 

object name 


Parameter Definitions 


Request Parameters: 


The supervisory object name must be ASCII characters and also be padded 
to the right with blanks if it is less than eight characters long. 


Return Codes 


The CH and CL registers contain a return code generated by the 
workstation program. System return codes use a function ID of X‘12’ or 
X‘13’ (found in the CH register). The error codes that can be received are: 


Code Meaning 


X ‘00’ Successful completion of the request. 
X‘OF’ The specified object is in an inaccessible environment. 
X‘2E’ The name is not found. 


Usage Notes 


This service does not allow names to be resolved across stoppable 
environments or allow code serialization semaphore names to be resolved 
from a stoppable environment to a nonstoppable environment. Also, the 
name of a component in a stoppable environment may never be resolved 
outside that environment. 
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Name Resolution 


Coding Example 


° 
f 


; PARAMETER LIST FOR NAME RESOLUTION 


SERVNAME DB 'KEYBOARD' 


; INITIALIZE REGISTERS FOR NAME RESOLUTION 
MOV AH, 81H ; AH = X'81' 
MOV DI,SEG SERVNAME ; SEGMENT ADDRESS OF PARM LIST 
MOV ES,DI ; ES SEGMENT ADDRESS OF PARM LIST 
MOV DI,OFFSET SERVNAME ; DI OFFSET ADDR. OF PARM LIST 


. 
‘ 


; SIGNAL WORKSTATION PROGRAM FOR NAME RESOLUTION SERVICE 


INT 7AH 
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ID Resolution 


Supervisory Object Service X‘01’: ID Resolution 


Use this service to resolve the specified supervisory object ID to its 
alphanumeric name. 


Register Values 


On Request On Completion 

AH = X‘01’ CH = Function ID 

DX = Supervisory object ID CL = Return code 

ES = Segment address of the parameter list 

DI = Offset address of the parameter list The contents of registers 


AX, BX, DX, ES, and DI 
are unpredictable. 


Register Definitions 
Request Registers: 
e The DX register contains the ID of the supervisory object. 
e The ES register contains the segment address of the parameter list. 


e The DI register contains the offset address of the parameter list. 


Parameter List Format 


Contents Contents 
Offset Length on Request on Completion 
O.-=-7 8 bytes Reserved Supervisory 
object name 


Parameter Definitions 


Completion Parameters: 


e The supervisory object name is the alphanumeric name assigned to the 
specified supervisory object when an entry for it was created in the SVC 
table. The supervisory object name can be a maximum of eight 
characters and is padded to the right with blanks if necessary. 
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ID Resolution 


Return Codes 
The CH and CL registers contain a return code generated by the 
workstation program. System return codes use a function ID of X‘12’ or 


X‘13’ (found in the CH register). The error codes that can be received are: 


Code Meaning 


X‘00’ Successful completion of the request. 
X‘05’ Invalid supervisory object ID. 
X‘OF’ The specified object is in an inaccessible environment. 


X‘2E’ The ID was not found in the SVC table. 


Usage Notes 


A task or component can resolve the ID of a supervisory object either 
within its own environment or within a nonstoppable environment. 


Coding Example 


; INITIALIZE REGISTERS FOR ID RESOLUTION 
MOV AH,0O1H 
MOV DX ,OBJECTID ; OBJECT ID IN DX 
MOV DI, SEG OBJNAME ; SEGMENT ADDRESS OF PARAMETER LIST 
MOV ES,DI ; IN ES 
MOV DI,OFFSET OBJNAME ; OFFSET OF PARAMETER LIST IN DI 
; SIGNAL WORKSTATION PROGRAM FOR ID RESOLUTION SERVICE 


INT 7AH 
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Delete Entry 


Supervisory Object Service X‘06’: Delete Entry 


Use this service to delete the entry in the SVC table representing the 
specified supervisory object. 


Register Values 


On Request On Completion 


AH = X‘06’ CH 
DX = Supervisory object ID CL 


Function ID 
Return code 


The contents of registers 
AX, BX, DX, ES, and DI 
are unpredictable. 


Register Definitions 
Request Registers: 
The DX register contains the ID of the supervisory object to be deleted from 


the SVC table. This object can only be a task, component, fixed-length 
queue, or semaphore within the requester’s environment. 


Return Codes 
The CH and CL registers contain a return code generated by the 
workstation program. System return codes use a function ID of X‘12’ or 


X‘13’ (found in the CH register). The error codes that can be received are: 


Code Meaning 


X‘00’ Successful completion of the request. 

X‘05’ Invalid supervisory object ID. 

X‘OF’ The specified object is in an inaccessible environment. 

X ‘30’ Cannot delete a task, fixed-length queue, or semaphore that has 
pending requests. 

X‘31’ Cannot delete a task that has timers. 


X‘3F’ Cannot delete a gate. 
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Delete Entry 


Usage Notes 


e Ifthe entry to be removed is a task, semaphore, or fixed-length queue 
and there are outstanding requests for the entry, then the entry will not 
be removed and an error indicator will be returned. 


e An application program running in a stoppable environment can only 
delete entries in its own environment. 


Coding Example 


; INITIALIZE REGISTERS FOR DELETE AN ENTRY REQUEST 
7 

MOV AH,O6H 

MOV DX,QUESID ; DX = FIXED LENGTH QUEUE ID 
7 


; SIGNAL WORKSTATION PROGRAM FOR DELETE AN ENTRY SERVICE 


INT 7AH 
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Delete Entry 
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Delete Entry 
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Introduction 


Introduction 


This chapter describes how to code requests for request services provided by 
the API. 


The request services allow your application program to write tasks that 
request services of other tasks, and tasks that respond to requests from 
other tasks. 


The request services provided by the API are: 


e Makea Request: Use this service to put a request queue element on 
the specified task’s request queue, or to directly invoke a component. 


e Geta Request: Use this service to obtain the contents of a request 
queue element on a task’s request queue. 


e Reply to a Request: Use this service to remove a specified request 
queue element from a task’s request queue and to send the specified 
reply to the requester. 


e Get Request Completion: Use this service to obtain the contents of 
a request queue element from a task’s completion queue. 


e Send a Signal toa Task: Use this service to send a signal to the 
specified task. 


Requesting the Request Services 


To use any of the request services, load the registers and the parameter list 
with the proper values, and use the INT 7AH instruction to signal the 
workstation program that it has a request to process. 


Return Codes for the Request Services 


16-2 


Return codes for the request services are 2-byte values made up of a 
function ID and an error code. The function ID indicates the portion of the 
workstation program in which the error occurred. The error number 
indicates the specific type of error that has occurred. An error number of 
X‘00’ indicates a successful acceptance or completion of the request. 


After your application has requested a request service, the CH and CL 
registers contain a return code generated by the request processing portion 
of the workstation program. The function ID is in the CH register, and the 
error number is in the CL register. The return codes that can be generated 
by request services are called system return codes. The function ID for 
system return codes is X‘12’ or X‘13’. The error numbers that can appear 
are specific to the service that was requested and are included in the 
descriptions of each service. 


See Appendix H, “Return Codes,” for more information. 


Make a Request 


Request Service X‘09’: Make a Request 


Use this service to put a request queue element (RQE) on the specified 
task’s request queue, or to directly invoke a component. 


Register Values 


On 


AH 
AL 
BH 
BL 
CX 
DX 
ES 
DI 


Register Definitions 


Request On Completion 
= X‘09’ AX = Request ID 
= Service number BL = Return type 
= Reply type CH = Function ID 
= Wait type CL = Return code 
= Request priority 
= Task, component, or gate ID The contents of registers 
= Segment address of the parameter list BH, DX, ES, and DI are 
= Offset address of the parameter list unpredictable. 


Request Registers: 


The AL register contains the service entry number of the requested 
service, if the request is being made to a gate. This register is not used 
on input if the request is being used to directly invoke a component or a 
task. 


The BH register specifies the type of reply your application program 
receives when the request is completed. Possible reply types are as 
follows: 


X‘80’ Request completion is indicated by a ‘completion’ signal. 
Any existing ‘completion’ signal to the application program 
is canceled. 


X‘40’ Request completion is indicated by an RQE on the 
application program’s completion queue. 


X‘20’ No notification of request completion is received. 
X‘10’ No notification of request completion is received, and the 
parameter list is copied into a 10-byte area so that the 


parameter list data area can be reused. This is intended for 
interrupt handler use. 
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Make a Request 
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7 
The BL register specifies the type of wait state your application 
program will go into until the request is completed. The type of wait is 
specified through a bit mask. When more than one type of wait is 
specified, the wait state ends when any one of the conditions is 
satisfied. The bits in the wait type mask are as follows: 


eee Sa ee (ae ©” Se Fe (| ee 


Request | Comp | Comp | Sema- | Timer | Signal 
queue queue | signal | phore 


— If bit 0 is set to 1, your application program waits until there is a 
request queue element in its request queue. If there is already an 
RQE in its request queue, the application stays dispatchable. 


— If bit 1 is set to 1, your application program waits until there is a 
request queue element in its completion queue. If there is already an 


RQE in its completion queue, the application stays dispatchable. 


— If bit 2 is set to 1, your application program waits until it receives a 
‘completion’ signal. 


— If bit 3 is set to 1, your application program waits until it receives a 
‘semaphore claimed’ signal. 


— If bit 4 is set to 1, your application program waits until it receives a 
‘timer tick’ signal. 


— If bit 5 is set to 1, your application program waits until it receives a 
‘generic’ signal. 


— If bit 6 is set to 1, your application program waits until it receives a 
‘data available’ signal. 


— Bit 7 is reserved and must be set to 0. 


Note: X00’ specifies “no wait.” A “wait” for semaphore or data is 
inappropriate for this service. 


The CX register indicates the priority of the request. Valid request 
priorities are 0 through 255, with 0 being the highest priority. 


The DX register indicates the ID of the task to which the request is to be 
sent, or the ID of the component being directly invoked, or a gate ID 
through which a request is being made. 


The ES register contains the segment address of the parameter list. 


The DI register contains the offset address of the parameter list. 


Make a Request 


Completion Registers: 


e The AX register contains the ID of the RQE that was placed on the 
requested task’s request queue. You can use this request ID to match 
outstanding requests with incoming completion queue elements. 


e The BL register indicates the type of wait condition that was satisfied to 
return control to your application program. The return type is specified 
through a bit mask. The bits in the return type mask have the same 
meaning as the bits in the wait type mask. 


Parameter List Format 
Contents Contents 
Offset Length on Request on Completion 


fo [ityte | Must be zero [Return code 1 
1 byt Function 1D 


You determine the format of the remainder of the parameter list on the basis 
of the needs of your particular application. 


Parameter Definitions 
Request Parameters: 
e Bytes 0 and 1 of the parameter must be X‘00’ on request. 


e You determine the format of the remainder of the parameter list on the 
basis of the needs of your particular application program. 


Completion Parameters: 


e Byte 1 of the parameter list contains a 2-digit function ID that indicates 
the portion of the requested task that processed the request. 


e Byte 0 of the parameter list contains a 2-digit error number that indicates 
what type of error (if any) caused request processing to fail. An error 


number of zero is used to indicate successful completion of the request. 


e You determine the format of the remainder of the parameter list on the 
basis of the needs of your particular application program. 
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Make a Request 


Return Codes 


Usage Notes 
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The CH and CL registers contain a return code generated by the workstation 
program. System return codes use a function ID of X‘12’ or X‘13’ (found in 
the CH register). The error codes that can be received are: 


Code Meaning 


X‘00’ * Successful completion of the request. 
X‘05’ Invalid index specified. 

X‘07’ Invalid reply type specified. 

X‘08’ Invalid wait type specified. 

X‘0B’ System RQE pool depleted. 

X‘34’ Invalid service number specified. 


* When the error number returned is X‘00’, you must also check the return 
code in the parameter list to be sure that return code X‘1314’ is not 
returned in the parameter list. See the note below for more information. 


You can use bytes 0 and 1 of the parameter list for return codes and function 
IDs from the requested task or component. You determine the return codes 
and function IDs that pertain to the request on the basis of the needs of your 
particular application program. 


Note: Your application may have used the Make a Request service to send a 
request to another task in an environment that is stopped, reset, or 
deleted before the request could be acted upon. In this case, bytes 0 and 
1 of the parameter list will contain return code X‘1814’. This return 
code indicates that the request cannot be completed. 


e This service cannot be requested between stoppable environments. 


e Ifyou are doing a Make Request with a parameter list, the first two bytes 
should be used as a return code function code field. 


e Generally, a task doing asynchronous processing should specify a reply 
of ‘completion queue’ signal. Tasks doing synchronous processing can 
specify a reply of ‘completion’ signal or a ‘completion queue’ signal. 


Coding Example 


e 
( 
° 
a 


° 
, 


f 


Make a Request 


INITIALIZE REGISTERS FOR MAKE A REQUEST 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


AH,O9H 

BH, 80H 

BL, 20H 

CX,60 

DX, TASKID 

DI, SEG PARMLIST 
ES,DI 

DI,OFFSET PARMLIST 


° 
q 
. 
f 
, 
° 
, 
. 
t 
. 
t 
f 


REPLY TYPE = COMPLETION SIGNAL 

WAIT TYPE = COMPLETION SIGNAL 

PRIORITY = 60 

TASK OR COMPONENT ID IN DX 

SEGMENT ADDRESS OF PARAMETER LIST 
IN ES 

OFFSET OF PARAMETER LIST IN DI 


SIGNAL WORKSTATION PROGRAM FOR MAKE A REQUEST SERVICE 


INT 


7AH 
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Get a Request 


Request Service X‘96’: Get a Request 


Use this service to obtain the contents of a request queue element (RQE) on 
a task’s request queue. 


Register Values 


On Request On Completion 

AH = X‘96’ AX = Request ID 

BL = Wait type BL = Return type 
CH = Function ID 
CL = Return code 
DX = Task ID 


Register Definitions 


ES = Segment address of 
the parameter list 

DI = Offset address of 
the parameter list 


The contents of register 
BH are unpredictable. 


Request Registers: 
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The BL register specifies the type of wait state your application program 
goes into until the request is completed. The type of wait is specified 
through a bit mask. If more than one type of wait is specified, the wait 
state ends when any one of the conditions is satisfied. The bits in the 
wait type mask are as follows: 


ae aa aes | Ee ee 


Request | Comp | Comp | Sema- | Timer | Signal | Data | Reserved 
queue queue | signal | phore 


— If bit 0 is set to 1, your application program waits until there is a 
request queue element in its request queue. If there is already an 
RQE in its request queue, the application stays dispatchable. 


— If bit 1 is set to 1, your application program waits until there is a 
request queue element in its completion queue. If there is already an 
RQE in its completion queue, the application stays dispatchable. 


— If bit 2 is set to 1, your application program waits until it receives a 
‘completion’ signal. 


— If bit 3 is set to 1, your application program waits until it receives a 
‘semaphore claimed’ signal. 


Get a Request 


— If bit 4 is set to 1, your application program waits until it receives a 
‘timer tick’ signal. 


— If bit 5 is set to 1, your application program waits until it receives a 
‘generic’ signal. 


— If bit 6 is set to 1, your application program waits until it receives a 
‘data available’ signal. 


— Bit 7 is reserved and must be set to 0. 


Note: X‘00’ specifies “no wait.” A “wait” for semaphore or data is 
inappropriate for this service. 


Completion Registers: 

e The AX register contains the ID of the RQE that was returned. 

e The BL register indicates the type of wait condition that was satisfied to 
return control to the requesting task. The return type is specified 
through a bit mask. The bits in the return type mask have the same 
meaning as the bits in the wait type mask. 


e The DX register contains the ID of the task that made the request. 


e The ES register contains the segment address of the parameter list. 


The DI register contains the offset address of the parameter list. 


Parameter List Format 


You define the format of the parameter list on the basis of the needs of your 
particular application program. 


Return Codes 
The CH and CL registers contain a return code generated by the workstation 
program. System return codes use a function ID of X‘12’ or X‘13’ (found in 


the CH register). The error codes that can be received are: 


Code Meaning 


X‘00’ Successful completion of the request. 
X‘09’ The request queue is empty. 
X‘36’ No request queue elements were on the request queue. 
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Get a Request 


Usage Notes 


e Ifthe request queue is empty and a wait type of “no wait” is specified, 
the request ID in the AX register on completion is set to zero and a 
“request queue empty” is received in the CL register. 


e Ifthe request queue is empty and a wait type other than “no wait” is 
specified, the task is set to the specified wait state until the request is 
satisfied. 


Coding Example 
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ta 


f 


INITIALIZE REGISTERS FOR GET A REQUEST 


MOV AH,96H 
MOV BL,80H ; WAIT TYPE = REQUEST QUEUE 


SIGNAL WORKSTATION PROGRAM FOR GET A REQUEST SERVICE 


INT 7AH 


Reply to a Request 


Request Service X‘82’: Reply to a Request 


Use this service to remove a specified request queue element (RQE) from a 
task’s request queue and send the specified reply to the requester. The 
process of removing the RQE and sending the reply is called completing the 


request. 
Register Values 
On Request On Completion 
AH = X‘82’ BL = Return type 
BL = Wait type CH = Function ID 
DX = RQE ID CL = Return code 


Register Definitions 


The contents of registers 
AX, BH, DX, ES, and DI 
are unpredictable. 


Request Registers: 


The BL register specifies the type of wait state your application program 
goes into until the request is completed. The type of wait is specified 
through a bit mask. If more than one type of wait is specified, the wait 
state ends when any one of the conditions is satisfied. The bits in the 
wait type mask are as follows: 


ae ae 34 
Request | Comp | Comp | Sema- | Timer | Signal] Data | Reserved 
queue queue | signal | phore 


— If bit 0 is set to 1, your application program waits until there is a 
request queue element in its request queue. If there is already an 
RQE in its request queue, the application stays dispatchable. 


— If bit 1 is set to 1, your application program waits until there is a 
request queue element in its completion queue. If there is already an 
RQE in its completion queue, the application stays dispatchable. 


— If bit 2 is set to 1, your application program waits until it receives a 
‘completion’ signal. 


— If bit 3 is set to 1, your application program waits until it receives a 
‘semaphore claimed’ signal. 


~ If bit 41s set to 1, your application program waits until it receives a 
‘timer tick’ signal. 
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Reply to a Request 


— If bit 5 is set to 1, your application program waits until it receives a 
‘generic’ signal. 


— If bit 6 is set to 1, your application program waits until it receives a 
‘data available’ signal. 


— Bit 7 is reserved and must be set to 0. 


Note: X‘00’ specifies “no wait.” A “wait” for semaphore or data is 
inappropriate for this service. 


e The DX register specifies the ID of the request queue element to be 
completed. A value of X‘0000’ indicates that the first element on the 
request queue is to be completed. 


Completion Registers: 
e The BL register indicates the type of wait condition that was satisfied to 
return control to the requesting task. The return type is specified 


through a bit mask. The bits in the return type mask have the same 
meaning as the bits in the wait type mask. 


Return Codes 
The CH and CL registers contain a return code generated by the workstation 
program. System return codes use a function ID of X‘12’ or X‘13’ (found in 


the CH register). The error codes that can be received are: 


Code Meaning 


X‘00’ Successful completion of the request 
X ‘09’ The request queue is empty 
X ‘36’ The specified request queue element was not on request queue. 


Usage Notes 
e The specified RQE is removed from the task’s request queue. 


e Ifthe request was issued with a reply type of X‘40’ (“completion queue”), 
the reply is added to the requesting task’s completion queue. 


e Ifthe request was issued with a reply type of X‘80’ completion’ signal), 
the requesting task is sent a ‘completion’ signal. The RQE is returned to 
the system RQE pool. 


e Ifthe request was issued with a reply type of X‘20’ or X‘10’ (““none” or 


“none—copy parameter list”), no reply is sent to the requesting task. The 
RQE is returned to the system RQE pool. 
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Reply to a Request 


Coding Example 


. 
f 


; INITIALIZE REGISTERS FOR REPLY TO A REQUEST 
MOV AH, 82H 
MOV BL,OOH ; WAIT TYPE = NO WAIT 
MOV DxX,0 ; 1ST RQE ON QUEUE 

; SIGNAL WORKSTATION PROGRAM FOR REPLY TO A REQUEST SERVICE 


INT 7AH 
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Get Request Completion 


Request Service X‘83’: Get Request Completion 


Use this service to obtain the contents of a request queue element (RQE) 
from a task’s completion queue. 


Register Values 


On Request On Completion 
AH = X‘83’ AX RQE ID 
BL = Wait type BL Return type 


CH Function [ID 

CL Return code 

ES = Segment address of 
the parameter list 

DI = Offset address of 
the parameter list 


hob wt al 


The contents of registers 
BH and DX are 
unpredictable. 


Register Definitions 
Request Registers: 


e The BL register specifies the type of wait state your application program 
goes into until the request is completed. The type of wait is specified 
through a bit mask. If more than one type of wait is specified, the wait 
state ends when any one of the conditions is satisfied. The bits in the 
wait type mask are as follows: 


jot ee 
queue queue | signal | phore 


— If bit 0 is set to 1, your application program waits until there is a 
request queue element in its request queue. If there is already an 
RQE in its request queue, the application stays dispatchable. 


— If bit 1 is set to 1, your application program waits until there is a 
request queue element in its completion queue. If there is already an 
RQE in its completion queue, the application stays dispatchable. 


— If bit 2 is set to 1, your application program waits until it receives a 
‘completion’ signal. 


— If bit 3 is set to 1, your application program waits until it receives a 
‘semaphore claimed’ signal. 
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Get Request Completion 
— If bit 4 is set to 1, your application program waits until it receives a 
‘timer tick’ signal. 


— If bit 5 is set to 1, your application program waits until it receives a 
‘generic’ signal. 


— If bit 6 is set to 1, your application program waits until it receives a 
‘data available’ signal. 


— Bit 7 is reserved and must be set to 0. 


Note: X‘00’ specifies “no wait.” A “wait” for semaphore or data is 
inappropriate for this service. 


Completion Registers: 

e The AX register contains the ID of the RQE that was returned. 

e The BL register indicates the type of wait condition that was satisfied to 
return control to the requesting task. The return type is specified 
through a bit mask. The bits in the return type mask have the same 
meaning as the bits in the wait type mask. 


e The ES register contains the segment address of the parameter list. 


e The DI register contains the offset address of the parameter list. 


Parameter List Format 


You define the format of the parameter list on the basis of the needs of your 
particular application program. 


Return Codes 
The CH and CL registers contain a return code generated by the workstation 
program. System return codes use a function ID of X‘12’ or X‘13’ (found in 
the CH register). The error codes that can be received are: 


Code Meaning 


X‘00’ Successful completion of the request 
X‘09’ The completion queue is empty. 


Usage Notes 
e If the request queue is empty and a wait type other than “no wait” is 


specified, the task is set to the specified wait state until the request is 
satisfied. 
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Get Request Completion 


Coding Example 


; INITIALIZE REGISTERS FOR GET REQUEST COMPLETION 
MOV AH,83H 


MOV BL,40H ; WAIT TYPE = COMPLETION QUEUE 


; SIGNAL WORKSTATION PROGRAM FOR GET REQUEST COMPLETION SERVICE 
INT 7AH 
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Send a Signal to a Task 


Request Service X‘12’: Send a Signal to a Task 


Use this service to send a signal to the specified task. 


Register Values 


On Request On Completion 


AH 
BL 
DX 


X‘12’ BL 
Wait type CH 
Task ID or X‘0000’ CL 


Return type 
Function ID 
Return code 


t i Wi 


The contents of registers 
AX, BH, DX, ES, and DI 
are unpredictable. 


Register Definitions 
Request Registers: 


e The BL register specifies the type of wait state your application program 
goes into until the request is completed. The type of wait is specified 
through a bit mask. If more than one type of wait is specified, the wait 
state ends when any one of the conditions is satisfied. The bits in the 
wait type mask are as follows: 


jo CO ae a ae Ce 
Request | Comp | Comp | Sema- | Timer | Signal! Data | Reserved 
queue queue | signal | phore 

— If bit 0 is set to 1, your application program waits until there is a 


request queue element in its request queue. If there is already an 
RQE in its request queue, the application stays dispatchable. 


— If bit 1 is set to 1, your application program waits until there is a 
request queue element in its completion queue. If there is already an 
RQE in its completion queue, the application stays dispatchable. 


— If bit 2 is set to 1, your application program waits until it receives a 
‘completion’ signal. 


— If bit 3 is set to 1, your application program waits until it receives a 
‘semaphore claimed’ signal. 


— If bit 4 is set to 1, your application program waits until it receives a 
‘timer tick’ signal. 


— If bit 5 is set to 1, your application program waits until it receives a 
‘generic’ signal. 
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Send a Signal toa Task 


Return Codes 


Usage Notes 


Coding Example 


— If bit 6 is set to 1, your application program waits until it receives a 
‘data available’ signal. 


— Bit 7 is reserved and must be set to 0. 


Note: X‘00’ specifies “no wait.” A “wait” for semaphore or data is 
inappropriate for this service. 


e The DX register contains the ID of the task to be signaled. A value of 
X‘0000’ indicates that the currently active task should be sent the signal. 
(This results in your application program’s sending a signal to itself.) 


Completion Registers: 


e The BL register indicates the type of wait condition that was satisfied to 
return control to the requesting task. The return type is specified via a 
bit mask. The bits in the return type mask have the same meaning as the 
bits in the wait type mask. 


The CH and CL registers contain a return code generated by the workstation 
program. System return codes use a function ID of X‘12’ or X‘13’ (found in 
the CH register). The error codes that can be received are: 


Code Meaning 


X‘00’ Successful completion of the request. 
X‘05” An invalid index was specified. 


A program running in a stoppable environment may send a signal only to 
tasks within its own environment. 


; INITIALIZE REGISTERS FOR SEND A SIGNAL TO A TASK 


MOV 
MOV 
MOV 


AH, 12H 
BL,04H . ; WAIT TYPE = SIGNAL 
DX,TASKSID ; TASK ID IN DX 


; SIGNAL WORKSTATION PROGRAM FOR SEND A SIGNAL TO A TASK SERVICE 


INT 
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Introduction 


Requesting the Task State Modifier Services 

Return Codes for the Task State Modifier Services 
Task State Modifier Service X‘9C’: 
Task State Modifier Service X‘02’: 
Task State Modifier Service X‘05’: 
Task State Modifier Service X‘08’: 
Task State Modifier Service X‘07’: 
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Introduction 


Introduction 


This chapter describes how to code requests for the task state modifier 
services provided by the API. 


The task state modifier services allow your application program to change 
the dispatch state or priority of a task. 


The task state modifier services provided by the API are: 


e Query Active Task: Use this service to obtain the ID and priority of 
the currently active task. 


e Set Task “Ready”: Use this service to set a specified task to the 
“ready” state. 


e Set Task “Unready”: Use this service to set a specified task to the 
“unready” state. 


e Set Task “Preemptable“: Use this service to set a specified task to 
the “preemptable” state. 


e Set Task “Nonpreemptable”: Use this service to set a specified task 
to the “nonpreemptable” state. 


e Change Task’s Priority: Use this service to change the specified 
task’s priority. 


e Return to Dispatcher: Use this service to return to the dispatcher 
from the requesting task. 


Requesting the Task State Modifier Services 


To request any of the task state modifier services, load the registers and the 
parameter list with the proper values, and use the INT 7AH instruction to 
signal the workstation program that it has a request to process. 


Return Codes for the Task State Modifier Services 
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Return codes for the Task State Modifier services are 2-byte values made up 
of a function ID and an error code. The function ID indicates the portion of 
the workstation program in which the error occurred. The code number 
indicates the specific type of error that has occurred. A code number of X‘00’ 
always indicates a successful acceptance or completion of the request. 


After your application has requested a task state modifier service, the CH 
and CL registers contain a return code generated by the request processing 
portion of the workstation program. The function ID is in the CH register, 
and the error code is in the CL register. The return codes that can be 
generated by semaphore management services are called system return codes. 
The function ID for system return codes is X‘12’ or X‘13’. The error codes 
that can appear are specific to the service that was requested and are 
included in the descriptions of each service. 


See Appendix H, “Return Codes,” for more information. 


Query Active Task 


Task State Modifier Service X‘9C’: Query Active Task 


Use this service to obtain the ID and priority of the currently active task. 


On Request On Completion 

AH = X‘9C’ AL = Priority 
CH = Function ID 
CL = Return code 
DX = Task ID 


The contents of registers 
AH, BX, ES, and DI are 
unpredictable. 


Register Definitions 
Completion Registers: 
e The AL register contains the priority of the currently active task. 


e The DX register contains the ID of the currently active task. 


Return Codes 
The CH and CL registers contain a return code generated by the workstation 
program. System return codes use a function ID of X‘12’ (found in the CH 
register). The system error code that can be received for this service is: 


Code Meaning 


X‘00’ Successful completion of the request. 


Coding Example 


; INITIALIZE REGISTERS FOR QUERY TASK 
MOV AH , 9CH 
; SIGNAL WORKSTATION PROGRAM FOR QUERY TASK SERVICE 


INT 7AH 
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Set Task “Ready” 


Task State Modifier Service X‘02’: Set Task “Ready” 


Register Values 


Use this service to set a specified task to the “ready” state. 


On Request On Completion 

AH = X‘02’ BL = Return type 
BL = Wait type CH = Function ID 
DX = Task ID CL = Return code 


Register Definitions 
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The contents of registers 
AX, BH, DX, ES, and DI 
are unpredictable. 


Request Registers: 


The BL register specifies the type of wait state your application program 
goes into until the request is completed. The type of wait 1s specified 
through a bit mask. If more than one type of wait is specified, the wait 
state ends when any one of the conditions is satisfied. The bits in the 
wait type mask are as follows: 


joe 
queue queue | signal | phore 


— If bit 0 is set to 1, your application program waits until there is a 
request queue element in its request queue. If there is already an 
RQE in its request queue, the application stays dispatchable. 


~ If bit 1 is set to 1, your application program waits until there is a 
request queue element in its completion queue. If there is already an 
RQE in its completion queue, the application stays dispatchable. 


— If bit 2 is set to 1, your application program waits until it receives a 
‘completion’ signal. 


— If bit 3 is set to 1, your application program waits until it receives a 
‘got semaphore’ signal. 


— If bit 4 is set to 1, your application program waits until it receives a 
‘timer tick’ signal. 


Return Codes 


Usage Notes 


Set Task “Ready” 


If bit 5 is set to 1, your application program waits until it receives a 
‘generic’ signal. 


If bit 6 is set to 1, your application program waits until it receives a 
‘data available’ signal. 


Bit 7 is reserved and must be set to 0. 


Note: X‘00’ specifies “no wait.” A “wait” for semaphore or data is 


inappropriate for this service. 


e The DX register contains the ID of the task to be set to the “ready” state. 


Completion Registers: 


e The BL register indicates the type of wait condition that was satisfied to 
return control to your application program. The return type is specified 
via a bit mask. The bits in the return type have the same meaning as the 
bits in the wait type mask. 


The CH and CL registers contain a return code generated by the workstation 
program. System return codes use a function ID of X‘12’ or X‘13’ (found in 
the CH register). The error codes that can be received for this service are: 


Code 


X‘00’ 
X‘05’ 
X‘OF’ 


Meaning 


Successful completion of the request. 
An invalid index was specified. 
Invalid environment access. 


e A program running in a stoppable environment cannot set tasks in other 
environments to the ready state. 


e The specified task is removed from the “unready” or “pending unready” 
state. 


e The specified task is made dispatchable if it is not waiting and not 
suspended. 
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Set Task “Ready” 


Coding Example 
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t 


° 
f 


° 
a 


. 


° 


INITIALIZE REGISTERS FOR SET TASK "READY" 


MOV AH,0O2H 


MOV BL,04H ; WAIT TYPE = SIGNAL 
MOV DX,TASKID ; TASK ID IN DX 
SIGNAL WORKSTATION PROGRAM FOR SET TASK "READY" SERVICE 


INT 7AH 


Set Task “Unready” 


Task State Modifier Service X‘05’: Set Task “Unready” 


Use this service to set a specified task to the “unready” state. 


Register Values 


On Request On Completion 

AH = X‘08’ BL = Return type 
BL = Wait type CH = Function ID 
DX = Task ID or X‘0000’ CL = Return code 


Register Definitions 


The contents of registers 
AX, BH, DX, ES, and DI 
are unpredictable. 


Request Registers: 


: CaaS ee Ce Fs ee 


The BL register specifies the type of wait state your application program 
goes into until the request is completed. The type of wait is specified via 
a bit mask. If more than one type of wait is specified, the wait state ends 
when any one of the conditions is satisfied. The bits in the wait type 
mask are as follows: 


Ca ae 
Request | Comp | Comp | Sema- | Timer | Signal| Data | Reserved 
queue queue | signal | phore 


— If bit 0 is set to 1, your application program waits until there is a 
request queue element in its request queue. If there is already an 
RQE in its request queue, the application stays dispatchable. 


— If bit 1 is set to 1, your application program waits until there is a 
request queue element in its completion queue. If there is already an 


RQE in its completion queue, the application stays dispatchable. 


— If bit 2 is set to 1, your application program waits until it receives a 
‘completion’ signal. 


— If bit 3 is set to 1, your application program waits until it receives a 
‘got semaphore’ signal. 


— If bit 4 is set to 1, your application program waits until it receives a 
‘timer tick’ signal. 
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Set Task “Unready” 


Return Codes 


Usage Notes 
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— If bit 5 is set to 1, your application program waits until it receives a 
‘generic’ signal. 


— If bit 6 is set to 1, your application program waits until it receives a 
‘data available’ signal. 


— Bit 7 is reserved and must be set to 0. 


Note: X‘00’ specifies “no wait.” A “wait” for semaphore or data is 
inappropriate for this service. 


e The DX register contains the ID of the task to be set to the “unready” 
state. If the value of the DX register is X‘0000’, the workstation program 
uses the ID of the currently executing task. 


Completion Registers: 


e The BL register indicates the type of wait condition that was satisfied to 
return control to your application program. The return type is specified 
via a bit mask. The bits in the return type have the same meaning as the 
bits in the wait type mask. 


The CH and CL registers contain a return code generated by the workstation 
program. System return codes use a function ID of X‘12’ or X‘13’ (found in 
the CH register). The error codes that can be received for this service are: 


Code Meaning 


X‘00’ Successful completion of the request. 
X‘05’ An invalid index was specified. 
X‘OF’ Invalid environment access. 


e A program running in a stoppable environment cannot set tasks in other 
environments to the unready state. 


e Ifthe specified task is already in the “unready” or “pending unready” 
state, there is no change. 


e If the specified task does not own any code serialization semaphores, it is 
set to the “unready” state. In the “unready” state, the task is not 
dispatchable. 


e If the specified task owns one or more code serialization semaphores, it is 
set to the “pending unready” state. In the “pending unready” state, 
dispatching is not affected. Once the task’s code serialization 
semaphores are released, the task is set to the “unready” state. 


e Ifthe specified task is the currently active task, the dispatcher takes 
control] as soon as the task sets itself unready. 


Set Task “Unready” 


Coding Example 


INITIALIZE REGISTERS FOR SET TASK "UNREADY" 


“eo =e Ne 


MOV AH,0O5H 
MOV BL, 20H ; WAIT TYPE = COMPLETION SIGNAL 
MOV DX, TASKID ; TASK ID IN DX 


SIGNAL WORKSTATION PROGRAM FOR SET TASK "UNREADY" SERVICE 


=e Se Ne 


INT 7AH 
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Set Task “Preemptable” 


Task State Modifier Service X‘08’: Set Task 
“Preemptable” 


Use this service to set a specified task to the “preemptable” state. 


Register Values 


On Request On Completion 


AH 
DX 


X‘08’ CH 
Task ID or X‘0000’ CL 


Function ID 
Return code 


ll tl 
ll 


The contents of registers 
AX, BX, DX, ES, and DI 
are unpredictable. 


Register Definitions 
Request Registers: 
e The DX register contains the ID of the task to be set to preemptable. If 


the value of the DX register is X‘0000’, the workstation program uses the 
ID of the currently executing task. 


Return Codes 


The CH and CL registers contain a return code generated by the workstation 
program. System return codes use a function ID of X‘12’ or X‘13’ (found in 
the CH register). The system return codes that can be received for this 
service are: 


Code Meaning 


X‘00’ Successful completion of the request. 
X ‘05’ An invalid index specified. 
X‘0OF’ Invalid environment access. 


Usage Notes 


e <A program running in a stoppable environment cannot set tasks in other 
environments to the preemptable state. 


e The preemptable state takes effect when the dispatcher makes the 
specified task the active task. The dispatcher selects the task to become 
active using the rules described at the beginning of this chapter. The 
task becomes preemptable until it goes into a wait state or becomes 
“unready.” When the task becomes active again, it will again become 
preemptable. 
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Set Task “Preemptable” 


‘Coding Example 


. 
f 


; INITIALIZE REGISTERS FOR SET TASK "PREEMPTABLE" 


MOV AH, 08H 
MOV DX, TASKID ; TASK ID IN DX 


; SIGNAL WORKSTATION PROGRAM FOR SET TASK "PREEMPTABLE" SERVICE 


INT 7AH 
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Set Task “Nonpreemptable” 


Task State Modifier Service X‘07’: Set Task 
“Nonpreemptable” 


Register Values 


Use this service to set a specified task to the “nonpreemptable” state. The 
task can be set either “nonpreemptable within priority” or “nonpreemptable 
within environment.” 


On Request . On Completion 
AH = X‘07’ CH = Function ID 
BH = Nonpreemptable type CL = Return code 
DX = Task ID or X‘0000’ 


Register Definitions 


Return Codes 
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The contents of registers 
AX, BX, DX, ES, and DI 
are unpredictable. 


Request Registers: 


The BH register indicates the nonpreemptable type, which is specified as 
follows: 


X‘01’ Nonpreemptable within priority 
X‘02? = Nonpreemptable within environment 


The DX register contains the ID of the task to be set to the 
“nonpreemptable” state. If the value of the DX register is X‘0000’, the 
workstation program uses the ID of the currently executing task. 


The CH and CL registers contain a return code generated by the workstation 
program. System return codes use a function ID of X‘12’ or X‘13’ (found in 
the CH register). The error codes that can be received for this service are: 


Code Meaning 


X‘00’ Successful completion of the request. 
X‘05’ An invalid index was specified. 
X‘0A’ Invalid nonpreemptable state. 

X‘OF’ Invalid environment access. 


Set Task “Nonpreemptable” 


Usage Notes 


e A program running in a stoppable environment cannot set tasks in other 
environments to the nonpreemptable state. 


e The nonpreemptable state takes effect when the dispatcher makes the 
specified task the active task. The dispatcher selects the task to become 
active using the rules described at the beginning of this chapter. The 
task becomes nonpreemptable until it goes into a wait state or becomes 
“unready.” When the task becomes active again, it again becomes 
nonpreemptable. 


Coding Example 


; INITIALIZE REGISTERS FOR SET TASK "NONPREEMPTABLE" 
MOV AH,0O7H 
MOV BH,0O1H ; NONPREEMPTABLE WITHIN PRIORITY 
MOV DX, TASKID ; TASK ID IN DX 

; SIGNAL WORKSTATION PROGRAM FOR SET TASK "NONPREEMPTABLE" SERVICE 


INT 7AH 
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Change Task’s Priority 
Task State Modifier Service X‘03’: Change Task’s 
Priority 


Use this service to change the specified task’s priority. The task’s priority 
can be set within the range of 36 through 64. © 


Register Values 


On Request On Completion 
AH = X‘03’ CH = Function ID 
CX = Task priority CL = Return code 
DX = Task ID or X‘0000’ 


The contents of registers 
AX, BX, DX, ES, and DI 
are unpredictable. 


Register Definitions 
Request Registers: 


e The CX register contains the specified task’s priority. The priority must 
be in the range of 36 through 64. 


e The DX register contains the ID of the task to be set to the specified 


priority. If the DX register contains X‘0000’, the supervisor uses the ID 
of the currently running task. 


Return Codes 
The CH and CL registers contain a return code generated by the workstation 
program. System return codes use a function ID of X‘12’ or X‘13’ (found in 


the CH register). The error codes that can be received for this service are: 


Code Meaning 


X‘00’ Successful completion of the request. 
X‘05’ An invalid index was specified. 

X‘06’ An invalid priority was specified. 
X‘OF’ Invalid environment access. 
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Change Task’s Priority 


Usage Notes 


e A program running in a stoppable environment cannot change the 
priority of tasks in other environments. 


e The new task priority takes effect. The nonpreemptable state takes effect 
when the dispatcher makes the specified task the active task. The 
dispatcher selects the task to become active using the rules described at 
the beginning of this chapter. 


Coding Example 


; INITIALIZE REGISTERS FOR CHANGE TASK'S PRIORITY 
MOV AH ,O3H 
MOV CX,PRIORITY ; TASK PRIORITY IN CX 
MOV DX ,TASKID ; TASK ID IN DX 
; SIGNAL WORKSTATION PROGRAM FOR CHANGE TASK'S PRIORITY SERVICE 


INT 7AH 
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Return to Dispatcher 


Task State Modifier Service X‘95’: Return to Dispatcher 


Use this service to return to the dispatcher from the requesting task. 


Register Values 


On Request On Completion 

AH = X‘985’ BL = Return type 

BL = Wait type CH = Function ID 
CL = Return code 


Register Definitions 


The contents of registers 
AX, BH, DX, ES, and DI 
are unpredictable. 


Request Registers: 
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The BL register specifies the type of wait state your application program 
goes into until the request is completed. The type of wait is specified 
through a.bit mask. If more than one type of wait is specified, the wait 
state ends when any one of the conditions is satisfied. The bits in the 
wait type mask are as follows: 


aes |: eee ee aes eae (a 
Request | Comp | Comp | Sema- | Timer | Signal} Data | Reserved 
queue queue | signal | phore 


— If bit 0 is set to 1, your application program waits until there is a — 
request queue element in its request queue. If there is already an 
RQE in its request queue, the application stays dispatchable. 


— If bit 1 is set to 1, your application program waits until there is a 
request queue element in its completion queue. If there is already an 
RQE in its completion queue, the application stays dispatchable. 


— If bit 2 is set to 1, your application program waits until it receives a 
‘completion’ signal. 


— If bit 3 is set to 1, your application program waits until it receives a 
‘got semaphore’ signal. 


— If bit 4 is set to 1, your application program waits until it receives a 
‘timer tick’ signal. : 


Return to Dispatcher 


— If bit 5 is set to 1, your application program waits until it receives a 
‘generic’ signal. 


— If bit 6 is set to 1, your application program waits until it receives a 
‘data available’ signal. 


— Bit 7 is reserved and must be set to 0. 


Note: X‘00’ specifies “no wait.” A “wait” for semaphore or data is 
inappropriate for this service. 


Completion Registers: 


e The BL register indicates the type of wait condition that was satisfied to 
return control to the requesting task. The return type is specified via a 
bit mask. The bits in the return type have the same meaning as the bits 
in the wait type mask. 


Return Codes 


The CH and CL registers contain a return code generated by the workstation 
program. System return codes use a function ID of X‘12’ or X‘13’(found in 
the CH register). The error code that can be received for this service is: 


Code Meaning 


X‘00’ Successful completion of the request. 


Coding Example 


INITIALIZE REGISTERS FOR RETURN TO DISPATCHER 


r 


MOV AH,95H 
MOV BL,O4H ; WAIT TYPE = SIGNAL 


r 
; SIGNAL WORKSTATION PROGRAM FOR RETURN TO DISPATCHER SERVICE 


f 


INT 7AH 
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Return to Dispatcher 
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Return to Dispatcher 
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Introduction 


Introduction 


This chapter describes how to code requests for the semaphore management 
request services provided by the API. 


The semaphore management services allow your application program to 
control access to resources and the execution of nonreentrant code. 


The semaphore management services provided by the API are: 
e Claim aSemaphore: Use this service to claim a specified semaphore. 


e Release a Semaphore: Use this service to release a specified 
semaphore. 


e Query a Semaphore: Use this service to determine whether a 
specified semaphore is claimed or free. 


Requesting the Semaphore Management Services 


2 


To request any of the semaphore management services, load the registers and 
the parameter list with the proper values, and use the INT 7AH instruction 
to signal the workstation program that it has a request to process. 


Return Codes for the Semaphore Management Services 
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Return codes for the semaphore management services are 2-byte values made 
up of a function ID and an error code. The function ID indicates the portion 
of the workstation program in which the error occurred. The error code 
indicates the specific type of error that has occurred. An error code of X‘00’ 
always indicates a successful acceptance or completion of the request. 


After your application has requested a semaphore management service, the 
CH and CL registers contain a return code generated by the request 
processing portion of the workstation program. The function ID is in the CH 
register, and the error code is in the CL register. The return codes that can 
be generated by semaphore management services are called system return 
codes. The function ID for system return codes is X‘12’ or X‘13’. The error 
codes that can appear are specific to the service that was requested and are 
included in the descriptions of each service. 


See Appendix H, “Return Codes,” for more information. 


Claim a Semaphore 


Semaphore Management Service X‘0D’: Claim a 


Semaphore 


Use this service to claim a specified semaphore. 


Register Values 


On Request On Completion 

AH = X‘0D’ BL = Return type 
BL = Wait type CH = Function ID 
DX = Semaphore ID CL = Return code 


Register Definitions 


The contents of registers AX, BH, 
DX, ES, and DI are unpredictable. 


Request Registers: 


The BL register specifies the type of wait state your application program 
goes into until the request is completed. The type of wait 1s specified 
through a bit mask. If more than one type of wait is specified, the wait 
state ends when any one of the conditions is satisfied. The bits in the 
wait type mask are as follows: 


jot 
queue queue | signal | phore 


— If bit 0 is set to 1, your application program waits until a request 
queue element is in its request queue. If an RQE is already in its 
request queue, the application stays dispatchable. 


— If bit 1 is set to 1, your application program waits until a request 
queue element is in its completion queue. If an RQE is already in 
its completion queue, the application stays dispatchable. 


— If bit 2 is set to 1, your application program waits until it receives a 
‘completion’ signal. 


— If bit 3 is set to 1, your application program waits until it receives a 
‘got semaphore’ signal. 


— If bit 4 is set to 1, your application program waits until it receives a 
‘timer tick’ signal. 


— If bit 5 is set to 1, your application program waits until it receives a 
‘generic’ signal. 
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Claim a Semaphore 


Return Codes 


Usage Notes 
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— If bit 6 is set to 1, your application program waits until it receives a 
‘data available’ signal. 


— Bit 7 is reserved and must be set to 0. 


Note: X‘00’ specifies “no wait.” A “wait” for data is inappropriate for 
this service. 


e The DX register contains the ID of the semaphore to be claimed. 
Completion Registers: 


e The BL register indicates the type of wait condition that was satisfied 
to return control to the requesting task. The return type is specified 
via a bit mask. The bits in the return type have the same meaning as 
the bits in the wait type mask. 


The CH and CL registers contain a return code generated by the 
workstation program. System return codes use a function ID of X‘12’ or 
X‘13’ (found in the CH register). The error codes that can be received for 
this service are: . 


Code Meaning 


X‘00’ Successful completion of the request. 

X ‘05’ Invalid index specified. 

X‘0B’ System RQE pool depleted. 

X‘2C’ Semaphore not claimed on wait. 

X‘3D’ Semaphore already claimed, no wait specified. 


e A program running in a stoppable environment may not claim 
semaphores in other stoppable environments. 


e A program running in a stoppable environment may claim a resource 
semaphore from a nonstoppable environment, but it will not be allowed 
to request the Name Resolution service for code serialization 
semaphores in a nonstoppable environment. 


Claim a Semaphore 


Coding Example 


; INITIALIZE REGISTERS FOR CLAIM A SEMAPHORE 

i 
MOV AH,ODH 
MOV BL,10H ; WAIT FOR SEMAPHORE SIGNAL 
MOV DX,SEMID ; SEMAPHORE ID 


; SIGNAL WORKSTATION PROGRAM FOR CLAIM A SEMAPHORE SERVICE 


INT 7AH 
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Release a Semaphore 


Semaphore Management Service X‘0A’: Release a 


Semaphore 


Register Values 


Use this service to release a specified semaphore. 


On Request On Completion 
AH = X‘0A’ CH = Function ID 
DX = Semaphore ID CL = Return code 


The contents of registers AX, BX, 
DX, ES, and DI are unpredictable. 


Register Definitions 


Return Codes 


Usage Notes 
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Request Registers: 


e The DX register contains the ID of the semaphore to be released. 


The CH and CL registers contain a return code generated by the 
workstation program. System return codes use a function ID of X‘12’ or 
X‘13’ (found in the CH register). The error codes that can be received for 
this service are: 


Code Meaning 


X‘00’ Successful completion of the request. 
X ‘05’ Invalid index specified. 
X‘0D’ Semaphore is already free. 


e A program running in a stoppable environment may not release 
semaphores in other stoppable environments. 


e The workstation program does not check that the semaphore is being 
released by the task that claimed it. This means that, for example, task 
A could claim a semaphore and then request to claim it again. The 
second claim request causes task A to be put in a wait state. Task B 
could, on completion of some action, release the semaphore. This 
action would cause task A’s second claim request to be honored, and 
task A could continue. 


Release a Semaphore 


Coding Example 


7 

; INITIALIZE REGISTERS FOR RELEASE A SEMAPHORE 
MOV AH , OAH 
MOV DX ,SEMID ; SEMAPHORE ID 


; SIGNAL WORKSTATION PROGRAM FOR RELEASE A SEMAPHORE SERVICE 


INT 7AH 
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Query a Semaphore 


Semaphore Management Service X‘0B’: Query a 


Semaphore 


Register Values 


Use this service to determine whether a specified semaphore is claimed or 
free. 


On Request On Completion 
AH = X‘0B’ BH = Semaphore type 
DX = Semaphore ID CH = Function ID 

CL = Return code 

DX = Task ID or X‘0000’ 


The contents of registers AX, BL, 
ES, and DI are unpredictable. 


Register Definitions 


Return Codes 
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Request Registers: 
e The DX register contains the ID of the semaphore to be queried. 
Completion Registers: 


e The BH register indicates the type of the specified semaphore, as 


follows: 
— X‘03’ = Resource semaphore 
— X‘04 = Code serialization semaphore 


e The DX register contains the ID of the task that claimed the semaphore, 
or X‘0000’ if the semaphore is free. 


The CH and CL registers contain a return code generated by the 
workstation program. System return codes use a function ID of X‘12’ or 
X‘13’ (found in the CH register). The error codes that can be received for 
this service are: 


Code Meaning 


X‘00’ Successful completion of the request. 
X‘05’ Invalid index specified. 


Query a Semaphore 


Usage Notes 


e A program running in a stoppable environment may not query 
semaphores in other stoppable environments. 


Coding Example 


; INITIALIZE REGISTERS FOR QUERY A SEMAPHORE 


MOV AH, OBH 
MOV DX,SEMID ; SEMAPHORE ID 


SIGNAL WORKSTATION PROGRAM FOR QUERY A SEMAPHORE SERVICE 


’ 


INT 7AH 
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Introduction 


Introduction 


This chapter describes how to code requests for the logical timer 
management request services provided by the API. 


The logical timer management services allow your application program to 
control time-dependent events through the use of logical timers. 


The logical timer management services provided by the API are: 


e Get Logical Timer: Use this service to get a logical timer for the 
specified task. 


e Set Logical Timer: Use this service to set the timer interval for a 
specified logical timer. 


e Release Logical Timer: Use this service to release a logical timer. 


Requesting the Logical Timer Management Services 


To request any of the logical timer management services, load the registers 
and the parameter list with the proper values, and use the INT 7AH 
instruction to signal the workstation program that it has a request to 
process. 


Return Codes for the Logical Timer Management Services 
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Return codes for the loyical timer management services are 2-byte values 
made up of a function ID and an error code. The function ID indicates the 
portion of the workstation program in which the error occurred. The error 
code indicates the specific type of error that has occurred. An error code of 
X‘00’ always indicates a successful acceptance or completion of the request. 


After your application has requested a logical timer queue management 
service, the CH and CL registers contain a return code generated by the 
request processing portion of the workstation program. The function ID is 
in the CH register, and the error code is in the CL register. The return 
codes that can be generated by logical timer management services are 
called system return codes. The function ID for system return codes is X‘12’ 
or X‘13’. The error codes that can appear are specific to the service that 
was requested and are included in the descriptions of each service. 


See Appendix H, “Return Codes,” for more information. 


Get Logical Timer 


Logical Timer Management Service X‘85’: Get Logical 


Timer 


Use this service to get a logical timer for the specified task. 


Register Values 


On 


AH 
BH 
DX 
ES 
DI 


Register Definitions 


Request On Completion 

= X‘85’ CH = Function ID 

= Timer interval CL = Return code 

= Task ID or X‘0000’ DX = Logical timer ID 

= Segment address of the timer flag 

= Offset address of the timer flag The contents of registers 
AX, BX, ES, and DI are 
unpredictable. 


Request Registers: 


The BH register contains the timer interval for the logical timer. The 
logical timers implemented by the workstation program use 18.2 timer 
ticks per second. Thus, to specify a logical timer interval of 1 second, 
you should specify a timer interval of 18; for a 2-second timer interval, 
you should specify a timer interval of 36, and so on. 


The DX register contains the ID of the task that will receive a ‘timer 
tick’ signal when the timer interval has elapsed. If the value of the DX 
register is X‘0000’, the workstation program uses the ID of the currently 
executing task. 


The ES and DI registers point to the timer flag, which is a 1-byte data 
area provided by your application program, that will be set to X‘FF” 
when the timer interval has elapsed. 


Completion Registers: 


The DX register contains the logical timer ID. 
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Get Logical Timer 


Return Codes 


The CH and CL registers contain a return code generated by the 
workstation program. System return codes use a function ID of X‘12’ or 
X‘13’ (found in the CH register). The error codes that can be received for 
this service are: 


Code Meaning 


X‘00’ Successful completion of the request. 
X‘05’ Invalid index specified. 
X‘11’ Logical timer pool depleted. 


Usage Notes 


e You must request the Set Logical Timer service to set the timer interval 
the first time. 


After the Set Logical Timer service is requested and the timer interval 
elapses once, the timer interval specified on the Get Logical Timer 
service will be used to reset the timer interval until the timer is 
released. The Set Timer service can be used at any time to override this 
reset value. 


If the timer interval specified on the Get Timer service was X‘00’, your 
application program must request the Set Logical Timer service to reset 
the timer interval each time the timer interval has elapsed. 


e Your application program can own multiple timers. You can determine 
which timer interval has elapsed by checking the 1-byte timer flag that 


is associated with each logical timer. 


e The task specified by its task ID is the task that receives the ‘timer tick’ 
signal when the timer interval has elapsed. 


Coding Example 


; INITIALIZE REGISTERS FOR GET LOGICAL TIMER 


DO NOT RESET THE TIMER 
USE THE CURRENTLY EXECUTING TASK'S ID 
ES:DI POINT TO THE TIMER FLAG 


MOV Dx,0 

MOV DI,SEG TIMERFLG 

MOV &ES,DI 

MOV DI,OFFSET TIMERFLAG 


=e 06sNe UN 


; SIGNAL WORKSTATION PROGRAM FOR GET A LOGICAL TIMER SERVICE 


INT 7AH 
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Set Logical Timer 


Logical Timer Management Service X‘84’: Set Logical 


Timer 


Use this service to set the timer interval for a specified logical timer. The 
specified task will receive a ‘timer tick’ signal when the timer interval has 


elapsed. 

Register Values 
On Request On Completion 
AH = X‘84’ BL = Return type 
BH = Timer interval CH = Function ID 
BL = Wait type CL = Return code 
DX = Logical timer ID 


Register Definitions 


The contents of registers 
AX, BH, DX, ES, and DI 
are unpredictable. 


Request Registers: 


The BL register specifies the type of wait state your application 
program goes into until the request is completed. The type of wait is 
specified through a bit mask. If more than one type of wait is specified, 
the wait state ends when any one of the conditions is satisfied. The bits 
in the wait type are as follows: 


Request = —_ Sema- | Timer fo Data {| Reserved 
queue queue | signal | phore 


— If bit 0 is set to 1, your application program waits until a request 
queue element is in its request queue. If an RQE is already in its 
request queue, the application stays dispatchable. 


— If bit 1 is set to 1, your application program waits until a request 
queue element is in its completion queue. If an RQE is already in 
its completion queue, the application stays dispatchable. 


— If bit 2 is set to 1, your application program waits until it receives a 
‘completion’ signal. 


— If bit 3 is set to 1, your application program waits until it receives a 
‘got semaphore’ signal. 


— If bit 4 is set to 1, your application program waits until it receives a 
‘timer tick’ signal. 
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Set Logical Timer 


— If bit 5 is set to 1, your application program waits until it receives a 
‘generic’ signal. 


— If bit 6 is set to 1, your application program waits until it receives a 
‘data available’ signal. 


— Bit 7 is reserved and must be set to 0. 


Note: X‘00’ specifies “no wait.” A “wait” for semaphore or data is 
inappropriate for this service. 


e The BH register contains the timer interval for the logical timer. The 
logical timers implemented by the workstation program use 18.2 timer 
ticks per second. Thus, to specify a logical timer interval of 1 second, 
you should specify a timer interval of 18; for a 2-second timer interval, 
you should specify a timer interval of 36, and so on. 


e The DX register contains the ID of the timer to be set. 

Completion Registers: 

e The BL register indicates the type of wait condition that was satisfied 
to return control to the requesting task. The return type is specified 
through a bit mask. The bits in the return type have the same meaning 


as the bits in the wait type mask. 


e The DX register contains the logical timer ID. 


Return Codes 


The CH and CL registers contain a return code generated by the 
workstation program. System return codes use a function ID of X‘12’ or 
X‘13’ (found in the CH register). The error codes that can be received for 
this service are: 


Code Meaning 


X‘00° Successful completion of the request. 
X‘05’ Invalid index specified. 


Usage Notes 


e After the specified timer interval has elapsed, the timer interval 
specified on the Get Logical Timer service is used to reset the timer 
interval until the timer is released. 


If the timer interval is specified as X‘00’ on the Get Logical Timer 
service, your application program must request the Set Logical Timer 
service to reset the timer interval each time the timer interval has 
elapsed. 
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Set Logical Timer 


e The task specified on the Get Logical Timer service is the task that 
receives the ‘timer tick’ signal when the timer interval has elapsed. 


Coding Example 


; INITIALIZE REGISTERS FOR SET A LOGICAL TIMER 


MOV AH , 84H 


MOV BH, 36 ; TIMER INTERVAL,APPROXIMATELY 2 SECONDS 
MOV BL,O8H ; WAIT TYPE,WAIT FOR TIMER TICK SIGNAL 
MOV DX, TIMERID + TIMER ID 


; SIGNAL WORKSTATION PROGRAM FOR SET A LOGICAL TIMER SERVICE 


INT 7AH 
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Release Logical Timer 


Logical Timer Management Service X‘8A’: Release 
Logical Timer 


Use this service to release a logical timer. Logical timers may be released 
only by the task that was specified on the Get Logical Timer request. 


Register Values 


On Request On Completion 


X‘8A’ CH Function ID 


AH = 
Logical timer ID CL = Return code 


DX 


Hl 


The contents of registers 
AX, BX, DX, ES, and DI 


are unpredictable. 


Register Definitions 
Request Registers: 


e The DX register contains the ID of the logical timer to be released. 


Return Codes 


The CH and CL registers contain a return code generated by the 
workstation program. System return codes use a function ID of X‘12’ or 
X‘13’ (found in the CH register). The error codes that can be received for 
this service are: 


Code Meaning 


X‘00° Successful completion of the request. 
X‘05’ Invalid index specified. 
X‘10" Requesting task does not own timer. 


Usage Notes 


Logical timers may be released only by the task that was specified on the 
Get Logical Timer request. 
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Release Logical Timer 


Coding Example 


; 
; INITIALIZE REGISTERS FOR RELEASE LOGICAL TIMER 
MOV AH,8AH 
MOV DX,TIMERID ; TIMER ID 
SIGNAL WORKSTATION PROGRAM FOR RELEASE LOGICAL TIMER SERVICE 


. 
’ 


INT 7AH 
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Introduction 


Introduction 


This chapter describes how to code requests for the fixed-length queue 
management request services provided by the API. 


The fixed-length queue management services allow your application 
program to pass data to other tasks or components, and to receive data from 


other tasks or components, using the fixed-length queue as a “pipeline” for 
the data. 


The fixed-length queue management services provided by the API are: 


e Enqueue Data: Use this service to enqueue data on the specified 
fixed-length queue. 


e Dequeue Data: Use this service to dequeue data from the specified 
fixed-length queue. 


e Purge Queue Data: Use this service to remove all data from the 
specified fixed-length queue. 


Requesting the Fixed-Length Queue Management Services 


To request any of the fixed-length queue management services, load the 
registers and the parameter list with the proper values, and use the INT 


7AH instruction to signal the workstation program that it has a request to 
process. 


Return Codes for the Fixed-Length Queue Management Services 


Return codes for the fixed-length queue management services are 2-byte 
values made up of a function ID and an error code. The function ID 
indicates the portion of the workstation program in which the error 
occurred. The error code indicates the specific type of error that has 
occurred. An error code of X‘00’ always indicates a successful acceptance 
or completion of the request. 


After your application has requested a fixed-length queue management 
service, the CH and CL registers contain a return code generated by the 
request processing portion of the workstation program. The function ID is 
in the CH register, and the error code is in the CL register. The return 
codes that can be generated by fixed-length queue management services are 
called system return codes. The function ID for system return codes is X‘12’ 
or X‘13’. The error codes that can appear are specific to the service that 
was requested and are included in the descriptions of each service. 


See Appendix H, “Return Codes,” for more information. 


20-2 


Enqueue Data 


Fixed-Length Queue Management Service 
X‘0C’: Enqueue Data 


Register Values 


Use this service to enqueue data on the specified fixed-length queue. 


On Request 

AH = X‘0C’ 

CX = Number of bytes 

DX = _ Fixed-length queue ID 
ES = Segment address of data 
DI = Offset address of data 


Register Definitions 


Return Codes 


Request Registers: 


On Completion 


AX = Number of bytes 
CH = Function ID 
CL = _ Return code 


The contents of registers 
BX, DX, ES, and DI are 


unpredictable. 


e The CX register contains the number of bytes to be enqueued on the 
specified fixed-length queue. 


e The DX register contains the ID of the fixed-length queue to receive the 


data. 


e The ES and DI registers point to the beginning of the data to be 
enqueued. 


Completion Registers: 


e The AX register contains the number of unused bytes currently left on 
the fixed-length queue if the number of bytes to be enqueued was too 
large. 


The CH and CL registers contain a return code generated by the 
workstation program. System return codes use a function ID of X‘12’ or 
X‘13’ (found in the CH register). The error codes that can be received for 
this service are: 


Code 


X‘00’ 
X‘05’ 
X‘39’ 


Meaning 


Successful completion of the request. 


Invalid index specified. 


Not enough room on fixed-length queue to enqueue the specified 


data. 
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Usage Notes 


Programs running in stoppable environments cannot enqueue data to 
fixed-length queues in other stoppable environments. 


Coding Example 


; INITIALIZE REGISTERS FOR ENQUEUE 


MOV AH,OCH 


MOV CX,2 ; NUMBER OF BYTES 

MOV DX,QUEUEID ; QUEUE ID 

MOV DI, SEG DATANAME  ; SEGMENT ADDRESS OF DATA 
MOV ES,DI ; IN ES 


MOV DI,OFFSET DATANAME OFFSET OF DATA IN DI 
; SIGNAL WORKSTATION PROGRAM FOR ENQUEUE SERVICE 


INT 7AH 
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Dequeue Data 


Fixed-Length Queue Management Service 
X‘13’: Dequeue Data 


Use this service to dequeue data from the specified fixed-length queue. 


Register Values 


On Request On Completion 


AH X‘13’ BL Return type 


BL = Wait type CH = _ Function ID 

CX = Number of bytes CL = _ Return code 

DX = _ Fixed-length queue ID DX = Number of bytes 

ES = Segment address of data 

DI = Offset address of data The contents of registers 
BH, AX, ES, and DI are 
unpredictable. 


Register Definitions 
Request Registers: 


e The BL register specifies the type of wait state your application 
program goes into until the request is completed. The type of wait is 
specified through a bit mask. If more than one type of wait is specified, 
the wait state ends when any one of the conditions is satisfied. The bits 
in the wait type mask are as follows: 


joa fe 
queue queue | signal | phore 


— If bit 0 is set to 1, your application program waits until a request 
queue element is in its request queue. If an RQE is already in its 
request queue, the application stays dispatchable. 


— If bit 1 is set to 1, your application program waits until a request 
queue element is in its completion queue. If an RQE is already in 
its completion queue, the application stays dispatchable. 


— If bit 2 is set to 1, your application program waits until it receives a 
‘completion’ signal. 


— If bit 3 is set to 1, your application program waits until it receives a 
‘got semaphore’ signal. 


— If bit 4 is set to 1, your application program waits until it receives a 
‘timer tick’ signal. 
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— If bit 5 is set to 1, your application program waits until it receives a 
‘generic’ signal. 


— If bit 6 is set to 1, your application program waits until it receives a 
‘data available’ signal. 


— Bit 7 is reserved and must be set to 0. 


Note: X‘00’ specifies “no wait.” A “wait” for semaphore is inappropriate 
for this service. 


e The CX register contains the number of bytes to be dequeued from the 
specified fixed-length queue. 


e The DX register contains the ID of the fixed-length queue. 


e The ES and DI registers point to the beginning of a data area provided 
by your application to contain the dequeued data. 


Completion Registers: 


e The DX register contains the number of bytes remaining on the 
fixed-length queue. 


e The BL register indicates the type of wait condition that was satisfied 
to return control to the requesting task. The return type is specified 
via a bit mask. The bits in the return type have the same meaning as 
the bits in the wait type mask. 


Return Codes 


The CH and CL registers contain a return code generated by the 
workstation program. System return codes use a function ID of X‘12’ or 
X‘13’ (found in the CH register). The error codes that can be received for 
this service are: 


Code Meaning 


X‘00’ Successful completion of the request. 

X ‘05’ Invalid index specified. 

X‘09’ The fixed-length queue is empty. 

X‘13’ Number of bytes requested is too large. 
X ‘37’ Not your turn to dequeue. 
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Dequeue Data 


Usage Notes 


e Programs running in stoppable environments cannot dequeue data from 
fixed-length queues in other stoppable environments. 


e If two or more tasks request the Dequeue Data service for the same 
fixed-length queue, the supervisor processes the requests in 
first-in-first-out (FIFO) order. 


Coding Example | 


. 
a 


; DATA AREA FOR DEQUEUE 


DOSESSID DB 4 DUP(O) ; DATA AREA TO RECEIVE 4 BYTES FROM THE 
; DEQUEUE 


° 
, 


; INITIALIZE REGISTERS FOR DEQUEUE 


MOV AH,13H 
MOV BL,02H 

MOV CX,0004H 

MOV DX,QUEUEID 

MOV DI,SEG DQSESSID 
MOV ES,DI 

MOV DI,OFFSET DQSESSID ; OFFSET ADDRESS OF DATA AREA IN DI 


WAIT UNTIL INFORMATION IS AVAILABLE 
DEQUEUE 4 BYTES 

FIXED-LENGTH QUEUE ID IN DX 

SEGMENT ADDRESS OF DATA AREA IN ES 


al al eT) 


; SIGNAL WORKSTATION PROGRAM FOR DEQUEUE SERVICE 


INT 7AH 


Chapter 20. Coding Fixed-Length Queue Management Services 20-7 


Purge Queue Data 


Fixed-Length Queue Management Service X‘0F’: Purge 
Queue Data | 


Use this service to remove all data from the specified fixed-length queue. 
Register Values 
On Request On Completion 


Function ID 
Return code 


AH 
DX 


X‘OF’ CH 
Fixed-length queue ID CL 


The contents of registers 
AX, BX, DX, ES, and DI 
are unpredictable. 


Register Definitions 
Request Registers: 


e The DX register contains the ID of the fixed-length queue. 


Return Codes 
The CH and CL registers contain a return code generated by the 
workstation program. System return codes use a function ID of X‘12’ or 
X‘13’ (found in the CH register). The error codes that can be received for 
this service are: 


Code Meaning 


X‘00’ Successful completion of the request. 
X‘05’ Invalid index specified. 


Usage Notes 


Programs running in stoppable environments cannot purge data from 
fixed-length queues in other stoppable environments. 
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Purge Queue Data 


Coding Example 


. 
, 


; INITIALIZE REGISTERS FOR PURGE QUEUE 


MOV AH, OFH 
MOV DX ,QUEUEID ; QUEUE ID 


; SIGNAL WORKSTATION PROGRAM FOR PURGE QUEUE SERVICE 


INT 7AH 
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Introduction 


Introduction 


This chapter describes how to code requests for the interrupt handler 
management services provided by the API. 


The interrupt handler management services allow environments to share 
the interrupt vector on a cooperative basis. On hardware interrupts, a 
device handler in any environment can receive control. On software 
interrupts, control is passed only to the software interrupt handler in the 
same environment as the code that issued the software interrupt, unless the 
interrupt handler was installed as a “global” software interrupt handler. 


The interrupt handler management services provided by the API are: 


e Install a Hardware Interrupt Handler: Use this service to identify 
an interrupt routine that is to gain control on hardware interrupts. 


e Install an Interrupt Handler: Use this service to identify an 
interrupt routine to gain control on software or hardware interrupts. 
This service also returns the entry point of the previous interrupt 
handler. For hardware interrupt handlers, the Install a Hardware 
Interrupt Handler service is the recommended service to use. 


e Query Interrupt Vector Contents: Use this service to obtain the 
entry point address of the second-level interrupt handler currently 
installed for the specified interrupt vector. 


Note: If you are querying the contents of an interrupt vector for interrupt 
handler chaining, the entry point returned by the Query Interrupt 
Vector Contents service should not be used. For interrupt handler 
chaining purposes, always use the entry point returned by the 
Install an Interrupt Handler service. 


e Remove an Interrupt Handler: Use this service to remove an 
interrupt handler that was installed through the Install a Hardware 
Interrupt Handler or Install an Interrupt Handler service request. 


Requesting the Interrupt Handler Management Services 
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To request any of the interrupt handler management services, load the 
registers and the parameter list with the proper values, and use the INT 
7AH instruction to signal the workstation program that it has a request to 
process. 


Introduction 


Return Codes for the Interrupt Handler Management Services 


Return codes for the interrupt handler management services are 2-byte 
values made up of a function ID and an error code. The function ID 
indicates the portion of the workstation program in which the error 
occurred. The error code indicates the specific type of error that has 
occurred. An error code of X‘00’ always indicates a successful acceptance 
or completion of the request. 


After your application has requested an interrupt handler management 
service, the CH and CL registers contain a return code generated by the 
request processing portion of the workstation program. The function ID is 
in the CH register, and the error code is in the CL register. The return 
codes that can be generated by interrupt handler management services are 
called system return codes. The function ID for system return codes is X‘12’ 
or X‘13’. The error codes that can appear are specific to the service that 
was requested and are included in the descriptions of each service. 


See Appendix H, “Return Codes,” for more information. 
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Install a Hardware 


Interrupt Handler 


Interrupt Handler Management Service X‘86’: Install a 
Hardware Interrupt Handler 


Use this service to identify an interrupt routine to gain control on 
hardware interrupts for devices that: 


e 
Register Values 


On 


AH 
BL 
CL 
DX 
ES 
DI 


Register Definitions 


Share a level 


Can be polled | 


Can be disabled. 


Request On Completion 

= X‘86’ CH = Function ID 

= Interrupt mask CL = Return code 

= Interrupt level DX = Interrupt 

= Status register handler ID 

= Segment address of the parameter list 

= Offset address of the parameter list The contents of 
registers AX, BX, ES, 
and DI are 
unpredictable. 


Request Registers: 


The BL register contains an 8-bit mask that is logically ANDed with the 
contents of the status register on hardware interrupts. A nonzero result 
indicates that the device is interrupting. If your device does not have a 
port that returns an interrupt status, install your handler using DOS 
function calls (X‘35’, X‘25’) or the Install an Interrupt Handler service. 


The CL register contains the hardware interrupt level, which can be in 
the range X‘00’ through X‘07’. 


The DX register contains the address of a status register I/O port. 
The ES register contains the segment address of the parameter list. 


The DI register contains the offset address of the parameter list. 


Completion Registers: 
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The DX register contains the ID of the interrupt handler. 


Install a Hardware Interrupt Handler 


Parameter List Format 


Contents Contents 
Offset | Length on Request on Completion 
2 1 word Segment address of the Unchanged 
interrupt handler 


1 word Offset address of the Unchanged 
interrupt handler 


110 port addres 


1 byte Byte to write on device Unchanged 
shutdown 


Parameter Definitions 


Return Codes 


Request Parameters: 


The first two words of the parameter list must point to the interrupt 
handler’s entry point. 


The I/O port address is the address of the port used to shut the device 
down. 


A port address of ‘0000X’ will prevent the device from being shut down 
on IPL. 


The byte to write on shutdown is written to the port on device 
shutdown. 


The CH and CL registers contain a return code generated by the 
workstation program. System return codes use a function ID of X‘12’ or 
X‘13’ (found in the CH register). The error codes that can be received for 
this service are: 


Code Meaning 


X‘00’ Successful completion of the request. 
X‘0E’ Invalid interrupt vector. 
X‘20° Interrupt handler control block pool depleted. 
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Install a Hardware Interrupt Handler 


Usage Notes 
Handlers installed with Install a Hardware Interrupt Handler service: 
e Get control with interrupts disabled. 
e Should never issue an EOI instruction. 
e Must do a device reset if the hardware requires it. 
e Should use a RETURN FAR instruction to return. 
e Should not swap stacks and then enable interrupts on an XMA system; 


this causes failure unless INDIBM2.SIF has been updated. See the 
User’s Guide for more information on updating INDIBM2.SIF. 


Coding Example 


° 
, 


; PARAMETER LIST FOR INSTALL A HARDWARE INTERRUPT HANDLER 


IHHANOFF DW 
IHHANSEG DW 
IHPORTAD DB 
IHBYTE DB 


OFFSET ADDRESS OF THE INTERRUPT HANDLER 
SEGMENT ADDRESS OF THE INTERRUPT HANDLER 
I/O PORT ADDRESS FOR SHUT-DOWN 

BYTE TO WRITE ON DEVICE SHUT-DOWN 


OO00 


; INITIALIZE PARAMETER LIST FOR INSTALL A HARDWARE INTERRUPT HANDLER 


MOV AX,OFFSET INTHANDL ; INTERRUPT HANDLER OFFSET INTO THE LIST 
MOV IHHANOFF , AX 


MOV AX,SEG INTHANDL ; INTERRUPT HANDLER SEGMENT INTO THE LIST 
MOV IHHANSEG,AX 

MOV AL,SHUTPORT ; SHUT-DOWN PORT ADDRESS INTO THE LIST 
MOV IHPORTAD,AL 

MOV AL,SHUTBYTE ; SHUT-DOWN BYTE INTO THE LIST 


MOV IHBYTE,AL 
; INITIALIZE REGISTERS FOR INSTALL A HARDWARE INTERRUPT HANDLER SERVICE 


MOV AH, 86H 
MOV BL ,MASK ; STATUS REGISTER MASK IN BL 
MOV CL, INTLEVEL ; INTERRUPT LEVEL IN CL 
MOV DX,STATADDR ; STATUS REGISTER IN DX 
MOV DI, SEG IHHANOFF ; SEGMENT ADDRESS OF PARAMETER LIST 
MOV ES,DI ; IN ES 
MOV DI,OFFSET IHHANOFF ; OFFSET OF PARAMETER LIST IN DI 
t 
; SIGNAL WORKSTATION PROGRAM FOR INSTALL A HARDWARE INTERRUPT HANDLER 
SERVICE 


‘ 


INT 7AH 
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Install an Interrupt Handler 


Interrupt Handler Management Service X‘87’: Install an 
Interrupt Handler 
Use this service to identify an interrupt routine that is to gain control on 


software or hardware interrupts. This service also returns the entry point 
of the previous interrupt handler to allow sharing a given interrupt. 


Register Values 


On Request On Completion 


X‘87’ CH Function ID 


BL = Flags CL = Return code 
CL = Interrupt vector DX = Interrupt 
ES = Segment address of handler ID 
the interrupt handler ES = Segment address of 
DI = Offset address of the previous interrupt 
the interrupt handler handler 


DI = Offset address of 
the previous interrupt 
handler 


The contents of registers AX and BX 
are unpredictable. 


Register Definitions 
Request Registers: 


e The BL register contains a flag byte that indicates how the interrupt 
handler will get control in the following format: 


through 5 


— Bits 0 through 5 are reserved. 

— Bits 6 and 7 are specified as follows: 
B‘00’ — local. This interrupt handler gets control only if the 
interrupt originated in the requester’s environment and if no 


“global” handlers, who do not chain, service it first. 


B‘10’ — global. This interrupt handler always gets control for 
interrupts on this level, regardless of the issuing environment. 


B‘01’ — global last resort. This interrupt handler gets control only 


if no other interrupt handlers service the interrupt. It services 
interrupts for all environments. 
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e The CL register contains the interrupt vector the requester wishes to 
claim. Valid interrupt vector values are 0 through 255, excluding 
vectors X‘50’ through X‘57’ and vector X‘7A’. 


e The ES register contains the segment address of the interrupt handler’s 
entry point. 


e The DI register contains the offset address of the interrupt handler’s 
entry point. 


Completion Registers: 
e The DX register contains the ID of the interrupt handler. 


e The ES register contains the segment address of the entry point of the 
interrupt handler previously recorded for this interrupt vector. 


e The DI register contains the offset address of the entry point of the 
interrupt handler previously recorded for this interrupt vector. 


Note: If both the ES and DI registers contain X‘0000’, do not chain to that 
address. Instead, use an IRET (interrupt return) instruction at the 
end of the interrupt handler code. 


For hardware interrupts, ES and DI always contain the entry point of a 
routine that chains to the next interrupt handler for this level. 


For software interrupts, ES and DI contain the entry point of the interrupt 
handler that previously would have been given control for an interrupt 
coming from the requester’s environment, on the basis of the values 
specified in the flag byte on request. For example, if the “global” option 
was specified and no other global handlers have been installed, ES and DI 
contain the entry point of the software first-level interrupt handler. If 
another global handler exists, ES and DI will contain the entry point of 
that handler. If the “local” option was specified, ES and DI contain the 
address of the handler that was servicing interrupts for this environment. 


Return Codes 


The CH and CL registers contain a return code generated by the 
workstation program. System return codes use a function ID of X‘12’ or 
X‘13’ (found in the CH register). The error codes that can be received for 
this service are: 


Code Meaning 


X‘00’ Successful completion of the request. 

X‘OE’ Invalid interrupt vector. 

X‘0F’ Invalid environment access. 

X‘20’ Interrupt handler control block pool depleted. 

X‘26’ Maximum number of software interrupt vectors already taken. 
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Usage Notes 


Coding Example 


. 
v 


f 


Install an Interrupt Handler 


If your interrupt handler is a local interrupt handler and it decides not 
to service an interrupt, it should jump to the address returned by this 
service in the ES and DI registers. If the ES and DI registers contain a 
value of zero, your interrupt handler should use the IRET instruction. 


If your interrupt handler is a global interrupt handler and it decides not 
to service an interrupt, it should jump to the address returned by this 
service in ESDI. 


If your interrupt handler services an interrupt, it should use the IRET 
instruction to return and thus discontinue chaining the interrupt. A 
hardware handler about to IRET must first do a RESET if hardware 
requires it and issue an EOI. 


If your interrupt handler attempts to chain to the previous handler with 
a PUSHF and far CALL instruction combination, the registers and the 
stack must first be restored. 


Your interrupt handler should not swap stacks and then enable 
interrupts on an XMA system; this causes failure unless INDIBM2.SIF 
has been updated. See the User’s Guide for more information on 
updating INDIBM2.SIF. 


INITIALIZE REGISTERS FOR INSTALL AN INTERRUPT HANDLER 


AH ,87H 


BL, FLAGS ; FLAGS 

CL, INTVECT ; INTERRUPT VECTOR 

DI, SEG INTHNDLR  ; SEGMENT ADDRESS OF PARAMETER LIST 
ES,DI ; INES 

DI,OFFSET INTHNDLR ; OFFSET OF PARAMETER LIST IN DI 


SIGNAL WORKSTATION PROGRAM FOR INSTALL AN INTERRUPT HANDLER 


INT 


7AH 
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Query Interrupt Vector Contents 


Interrupt Handler Management Service X‘88’: Query 
Interrupt Vector Contents 


Register Values 


Use this service to obtain the entry point address of the second-level 
interrupt handler currently installed for the specified interrupt vector. Do 
not use this service for global chaining. 


On Request On Completion 


AH = X‘88’ CH 
CL = Interrupt vector CL 


Function ID 

Return code 
Segment address of 
the interrupt handler 
DI = Offset address of 

the interrupt handler 


Holl dl 


The contents of registers AX, BX, and DX 
are unpredictable. 


Register Definitions 
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Request Registers: 


e The CL register contains the interrupt vector the requester wishes to 
query. Valid interrupt vector values are 0 through 255. 


Completion Registers: 


e The ES register contains the segment address of the entry point of the 
interrupt handler currently installed for this interrupt vector. 


e The DI register contains the offset address of the entry point of the 
interrupt handler currently installed for this interrupt vector. 


Note: If both the ES and DI registers contain X‘0000’, do not chain to that 
address. Instead use an IRET (Interrupt Return) instruction at the 
end of the interrupt handler code. 


For hardware interrupts, ES and DI always contain the entry point of a 
routine that chains to the next interrupt handler for this level. 


For software interrupts, ES and DI contain the entry point of the interrupt 
handler that previously would have been given control for an interrupt 
coming from the requester’s environment, after the global interrupt 
handlers had checked the interrupt. That is, if a local interrupt handler 
was installed, ES and DI contain the address of this local handler. 
Otherwise, ES and DI contain the address of the original contents of the 
interrupt vector before any local handlers were installed. 


Return Codes 


Usage Notes 


Coding Example 


Query Interrupt Vector Contents 


The CH and CL registers contain a return code generated by the 
workstation program. System return codes use a function ID of X‘12’ or 
X‘13’ (found in the CH register). The error code that can be received for 
this service is: 


Code Meaning 


X‘00’ Successful completion of the request. 


If you are querying the contents of an interrupt vector for interrupt handler 
chaining purposes, the entry point returned by the Query Interrupt Vector 
Contents service should not be used. For interrupt handler chaining 
purposes, always use the entry point returned by the Install a Software 
Interrupt Handler service. 


; INITIALIZE REGISTERS FOR QUERY INTERRUPT VECTOR CONTENTS 


MOV 
MOV 


AH, 88H 
CL,9 ; INTERRUPT VECTOR IN BL 


; SIGNAL WORKSTATION PROGRAM FOR QUERY INTERRUPT VECTOR CONTENTS 


INT 


7AH 
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Interrupt Handler Management Service X‘89’: Remove 
an Interrupt Handler 


Use this service to remove an interrupt handler that was installed through 
the Install a Hardware Interrupt Handler or Install an Interrupt Handler 
service request. 


If the interrupt handler was installed through the Install a Hardware 
Interrupt Handler service, the device is shut down according to the 
information supplied when the hardware interrupt handler was installed. 


Register Values 


On Request On Completion 


AH X‘89’ CH 


= Function ID 
DX = Interrupt handler ID CL 


Return code 


Il 


The contents of registers AX, BX, DX, 
ES, and DI are unpredictable. 


Register Definitions 
Request Registers: 


e The DX register contains the ID of the interrupt handler to be removed. 


Return Codes 


The CH and CL registers contain a return code generated by the 
workstation program. System return codes use a function ID of X‘12’ or 
X‘13’ (found in the CH register). The error codes that can be received for 
this service are: 


Code Meaning 


X‘00’ Successful completion of the request. 
X ‘05’ Invalid ID specified. 
X ‘OF’ Invalid environment access. 
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Coding Example 


; INITIALIZE REGISTERS FOR REMOVE AN INTERRUPT HANDLER 


MOV AH, 89H 
MOV DX,HNDLRSID ; INTERRUPT HANDLER ID 


; SIGNAL WORKSTATION PROGRAM FOR REMOVE AN INTERRUPT HANDLER 


INT 7AH 
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Remove an Interrupt Handler 
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Introduction 


Introduction 


Environments 


The environment manager portion of the workstation program allows you 
to divide memory, resources, and supervisory objects into several groupings, 
called environments. You can designate an environment to be used to run 
DOS or an application program. Environments used to run DOS and DOS 
applications are called stoppable environments. You can alternatively 
designate an environment to be used to run a system extension that is 
loaded as part of the workstation program. Environments used in this way 
are called nonstoppable environments. 


The environment manager allows you to stop the program running in a 
stoppable environment, releasing any resources that were added to the 
environment by that program’s request. After you stop the program 
running in a stoppable environment, you can restart a different program in 
that environment without re-[PLing the entire system. The Stop/Reset 
service corresponds to the Ctrl-Alt-Del key sequence offered by DOS in 
base PC mode. 


The environment manager also provides services that allow you to suspend 
or resume an environment. When you suspend an environment, the 
supervisor sets all the tasks running in that environment to the unready 
state until you resume that environment. When you resume an 
environment, the supervisor sets all the tasks in that environment to the 
ready state. The Suspend/Resume service corresponds to the Ctrl-NumLock 
key sequence offered by DOS in base PC mode. 


An environment may contain memory, system control blocks, and system 
data areas created or accessed by user program requests. For example, an 
application program that creates multiple windows will have a record of 
each of those windows in its environment definition. 


Stoppable Environments 
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A stoppable environment is used for running DOS or personal computer 
application programs. Stoppable environments can be used for any program 
that can be removed from the system without causing other programs to 
fail. That is, programs in stoppable environments must not offer services to 
programs running in any other environments. Programs running in 
stoppable environments can be stopped by any program running in the same 
environment including itself, by a program running in a nonstoppable 
environment, or by the user by pressing the Ctrl-Alt-Del keys in that 
sequence. 


Introduction 


Nonstoppable Environments 


Nonstoppable environments are used to run system extensions, which are 
loaded as part of the workstation program and start running automatically 
when the workstation program is IPLed. System extensions cannot be 
removed from the system without recustomizing. A system extension may 
offer services that other programs can use. 


Environment Access Restrictions 


A program in a stoppable environment should never offer services or 
supervisory objects that other programs may depend on. To prevent this, 
restrictions on access rights of stoppable environments will be enforced. 
These restrictions are as follows: 


1. Stoppable environments are only allowed to access system resources 
created within that environment, or within a nonstoppable 
environment. For instance, a stoppable environment may not claim 
another stoppable environment’s semaphore, or access its fixed-length 
queue, or send a work request to a task in another stoppable 
environment. This restriction is enforced at name resolution time. 
Nonstoppable environments are allowed to access all system resources, 
but resources belonging to stoppable environments must be managed by 
a resource manager. 


2. A program in a stoppable environment may not change the priority, 
preemptability, or dispatch status of a task outside that environment. 
This cannot be enforced at name resolution time. Instead, it will be 
enforced when the specific request is made. 


3. A component within a stoppable environment may not be invoked by 
any other environment. Access restrictions to the component ID are 
enforced at name resolution time. 


4. A stoppable environment cannot create a gate. This is enforced when 
the environment attempts to create the gate. 


5. A stoppable environment cannot stop, suspend, or resume an 
environment other than its own. It can never reset any environment, 
including its own. 


6. A stoppable environment cannot name-resolve a code serialization 
semaphore that belongs to a nonstoppable environment. This is 
enforced at name resolution time. 


7. A nonstoppable environment can only reset its own environment, but it 


can stop any stoppable environment. A nonstoppable environment can 
also suspend or resume any environment. 
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Environment Management Services Your Program or System Extension Can 
Use to Control Environments 


Application programs and system extensions can use the following services 
to control environments. Application programs must observe the 
environment access restrictions listed on page 22-3. The following services 
and their coding examples may be found in Chapter 23, “Coding 
Environment Manager Services.” 


e Suspend/Resume Environment: Use this service to suspend or 
resume all tasks in the specified environment. You can also use this 
service to suspend or resume all tasks in the specified environment 
except the task that is requesting the service. 


e Stop/Reset Environment: Use this service to stop or reset the 
specified environment. 


e Query Task’s Environment ID: Use this service to obtain the ID of 
the environment associated with the specified task. 


e Query Environment Characteristics: Use this service to obtain a 
list of characteristics associated with a specified environment. 


Resource Managers 


A resource is anything, such as control blocks, storage, or physical devices 
(for example, a printer), that a system extension allocates or deallocates. A 
resource is generally represented as a control block or data area. A 
resource chain is a grouping of these data areas or control blocks. 
Resources are chained per environment. 


You can code a system extension to provide services or allocate resources 
to stoppable environments. A resource manager can only exist in a 
nonstoppable environment. The portion of a system extension that 
allocates and deallocates a specified resource is called a resource manager. 
A resource manager must be identified to the environment manager before 
it can begin its resource management operations. You can identify more 
than one resource manager per environment. Alternatively, each resource 
manager may have more than one resource chain (one per environment), 


To act as a resource manager, your system extension should do the 
following: 


e Request the Create Component Entry service to create a component 
called the cleanup component, which the environment manager calls to 
recover the resources allocated to an environment when that 
environment is stopped. 


e Obtain a resource manager ID by requesting the Identify Resource 


Manager service. Your resource manager must use this ID in all 
subsequent interaction with the environment manager. 
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e Request the Add Resource service each time a resource is allocated to 
an application program. The environment manager will add the 
resource to the top of the environment’s chain. 


e Request the Delete Resource service each time a resource is deallocated 
normally from the application. 


To add resources to or delete resources from a resource chain, the resource 
manager uses the Add Resource or Delete Resource service. Each resource 
is assumed to be a data area that contains as its first element a 2- or 4-byte 
field that the environment manager uses to link the resources. The size of 
the field is determined by a parameter that is required on the Identify 
Resource Manager request. 


A resource manager has a component that is called by the environment 
manager when a stoppable environment to which the system extension has 
allocated resources is being stopped. This allows the resource manager to 
reclaim resources outstanding in that stoppable environment. In order for 
your resource manager’s cleanup component to be notified when a PC 
environment is stopped (so your resource manager can reclaim resources 
used for that PC environment), it must have added at least one resource to 
the PC environment’s chain. 


When a stoppable environment is re-[PLed or stopped, the environment 
manager notifies the cleanup component by sending the address of each 
resource on the resource chain. This allows the cleanup component to’ 
recover the resources that have been allocated to the stoppable 
environment. See “The Cleanup Component Interface” on page 23-32 for 
more information. 


If the application is stopped (either voluntarily or involuntarily) and there 
are outstanding resources allocated to the application, the environment 
manager will call the cleanup component once for each resource on the 
chain of allocated resources, passing a parameter list. The cleanup 
component should request the Delete Resource service each time it is 
called, to delete the resource. In this way, the cleanup component recovers 
all the resources allocated by the application program. 


When a PC environment is stopped, the environment manager will notify 
all the resource manager’s cleanup components that have a resource on the 
PC environment chain that the environment is being stopped. Thus it is 
important for your resource manager to add a resource to any PC 
environment about which it is to be notified. If your resource manager that 
handles requests from a PC is a component, then it is running under the 
PC task that is in the PC environment, and it can simply add a resource to 
the current active task environment. 


If the resource manager that handles requests from a PC is a task, then it 
is executing in a different environment from the PC. When it received the 
request through the Make a Request service, the DX register contained the 
task ID of the task that made the request. Your resource manager will add 
a resource to the environment of the task (in the DX register) that made the 
request. 
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Environment Management Services Your System Extension Can Use to 
Control Resource Management 
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Your system extension can use the following services to control resource 
management: 


Identify Resource Manager: Use this service to identify a resource 
manager to the environment management portion of the workstation 
program. 


Add Resource: Use this service to add a resource to the top of the 
resource chain, or to move a resource already on the chain to the top of 
the chain for a specified environment. 


Delete Resource: Use this service to delete a resource from a 
resource chain. 


Query Resource: Use this service to obtain the address of the first 
resource in a specified resource chain. 


These services and their coding examples are described in 
Chapter 23, “Coding Environment Manager Services.” 


Resource Managers 
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This chapter describes how to code requests for the environment manager 
services provided by the API. Before using it, you should have read the 
introductory discussion in Chapter 22, “Environments and the 
Environment Manager.” 


The environment manager services allow your application program to 
control its environment, and allow a system extension to act as a resource 
manager to control the allocation and deallocation of resources to 
application programs running in stoppable environments. 


Environment manager services that your application program and system 
extension can use are: 


e Suspend/Resume Environment: Use this service to suspend or 
resume all tasks in the specified environment. You can also suspend or 
resume all tasks in the environment except the task that is requesting 
the service. 


e Stop/Reset Environment: Use this service to stop or reset the 
environment. Reset should only be used by system extensions. 


e Query Task’s Environment ID: Use this service to obtain the ID of 
the environment associated with a task. 


e Query Environment Characteristics: Use this service to obtain a 
list of characteristics associated with an environment. 


Additional environment manager services that your system extension can 
use to control resource management are: 


e Identify Resource Manager: Use this service to identify a resource 
manager to the environment management portion of the workstation 
program. 


e Add Resource: Use this service to add a resource to the top of the 
resource chain, or to move a resource already on the chain to the top of 
the chain for an environment. 


e Delete Resource: Use this service to delete a resource from a 
resource chain. 


e Query Resource: Use this service to obtain the address of the first 
resource in a resource chain. 


Introduction 


Requesting the Environment Manager Services 


To request any of the environment manager services, load the registers and 
the parameter list with the proper values, and use the INT 7AH instruction 
to signal the workstation program that it has a request to process. 


Return Codes for the Environment Manager Services 


Return codes for the environment manager services are 2-byte values made 
up of a function ID and an error code. The function ID indicates the 
portion of the workstation program in which the error occurred. The error 
number indicates the specific type of error that has occurred. An error 
code of X‘00’ always indicates a successful acceptance or completion of the 
request. 


After your application has requested an environment manager service, the 
CH and CL registers contain a return code generated by either the request 
processing portion or the environment management portion of the 
workstation program. The function ID is in the CH register, and the error 
code is in the CL register. Environment manager services that require a 
parameter list have additional return codes in bytes 0 and 1 of the 
parameter list on completion. The function ID is in byte 1, and the error 
code is in byte 0. The function ID for system return codes is X‘12’. The 
function ID for environment manager return codes is X‘13’. The error codes 
that can appear are specific to the service that was requested and are 
included in the descriptions of each service. 


See Appendix H, “Return Codes,” for more information. 
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Environment Manager Service X‘10’: Identify Resource 
Manager | 


Your system extension can identify itself as a resource manager to the 
environment manager portion of the workstation program. A resource 
manager resides in a nonstoppable system extension and allocates resources 
to stoppable environments. The environment manager assigns an ID to the 
resource manager and establishes a unique resource chain for the resource 
manager. 


Before you can request this service, you must create a component by using 
the Create Component service. This component, called the cleanup 
component, is invoked whenever an environment that has resources 
allocated by this resource manager is stopped, reset, or deleted. 


Register Values 


On Request On Completion 

AH = X‘10’ CH = X‘12’ or X‘13’ 
BH = Priority of the cleanup component CL = Return code 
CX = X‘0000’ or segment value DL = Resource 
DX = ID of the cleanup component manager ID 


The contents of registers 
AX, BX, DH, ES, and DI 
are unpredictable. 


Register Definitions 
Request Registers: 


e The BH register contains the priority at which to run the cleanup 
component. This priority must be in the range 1 through 64. If a task 
in the resource manager receives requests on a fixed-length queue from 
an application program, the cleanup component should run at a lower 
priority than that task, since the Stop/Reset Environment service does 
not track or clean up items placed on a fixed-length queue by a 
terminating environment. Running the cleanup component at a lower 
priority ensures that the data enqueued by the application is dequeued 
by the system extension before the cleanup component runs. 


e The CX register indicates whether the resource manager’s resource 
chain will be linked by 1-word or doubleword pointers. If a segment 
value is coded in the CX register on request, the resource manager 1s 
indicating that all resources that will be added to its resource chain 
reside in the specified segment and, thus, are linked by 1-word pointers. 
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Identify Resource Manager 


The environment manager uses the specified segment value for Query 
Resource, Add Resource, and Delete Resource requests. If X‘0000’ is 
coded in the CX register on request, the resource manager is indicating 
that all resources that will be added to its resource chain will be linked 
by doubleword pointers. 


If the resources in the resource chain are linked by 1-word pointers, 
each resource data area or control block must begin with a 1-word field 
that will be used by the environment manager for chaining. If the 
resources in the resource chain are linked by doubleword pointers, each 
resource control block must begin with a doubleword field that will be 
used by the environment manager for chaining. 


e The DX register contains the ID of the cleanup component, which will 
reclaim all of this resource manager’s resources whenever an 
environment using them is stopped, reset, or deleted. The cleanup 
component is given a data chain pointer and an indication of the type 
“stop.” The cleanup component runs under the environment manager’s 
task at the specified priority, and also runs off the environment 
manager’s task’s stack. This stack only has 80 bytes available for the 
cleanup component to use. If 80 bytes is not sufficient, the cleanup 
component switches to its own stack when it gets control. 


The cleanup component is invoked once for each resource on the 
resource chain for the environment being stopped, reset, or deleted. 

The environment manager notifies the cleanup component when an 
environment is stopped, reset, or deleted. See “The Cleanup Component 
Interface” on page 23-32 for more information. 


The cleanup component must request the Delete Resource service for 
each resource it has cleaned up in order to remove the resources from 
the stopping environment. 


Completion Registers: 
e The DL register contains the resource manager ID assigned to this 


resource manager. This ID identifies a unique chain for a resource 
manager within each environment. 


The CH and CL registers contain a return code generated either by the 
supervisor portion of the workstation program or by the environment 
manager portion of the workstation program. 
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Usage Notes 
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Supervisor return code: 

The supervisor return codes use a function ID of X‘12’ (found in the CH 
register). The error code that can be received is found in the CL 
register: 

Code Meaning 

X‘05’ Invalid SVC ID. 

Environment manager return codes: 

Environment manager return codes use a function ID of X‘13’ (found in 
the CH register). The error codes that can be received are found in the 
CL register: 

Code Meaning 

X‘00’ Successful completion. 


X‘05’ The specified ID is not a component. 
X ‘06’ Invalid priority. 


X‘0F’ Invalid environment access. This service must be requested 
from a nonstoppable environment. 

X25” The maximum number of resource managers has already been 
defined. 


See Appendix H, “Return Codes,” for more information. 


This service may be requested only by a nonstoppable system extension. 


This service needs to be requested only by a resource manager that 
wants to be notified when a stoppable environment is being stopped, 
reset, or deleted, so that it may clean up any resources that it allocated 
on the stoppable environment’s behalf. 


This service should be requested once by a resource manager when it is 
brought into the system, usually in the system extension’s initialization 
code. 


Before you request the Identify Resource Manager service, you must 
request the Create Component service to create the component that will 
clean up any resources allocated by the resource manager. 


The cleanup component is invoked once for each of its resources. The 
component must issue a Delete Resource to have that resource deleted. 


Identify Resource Manager 


Coding Example 


INITIALIZE REGISTERS FOR IDENTIFY RESOURCE MANAGER 


=e Ne fO 


MOV AH, 10H 
MOV BH,50 PRIORITY OF THE CLEANUP COMPONENT 


MOV CX, SEGVAL ; SEGMENT VALUE 
MOV DX ,CLEANCID ; CLEANUP COMPONENT ID 


SIGNAL WORKSTATION PROGRAM FOR IDENTIFY RESOURCE MANAGER SERVICE 


° 
, 


INT 7AH 
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Environment Manager Service X‘8E’: Add Resource 


Use this service to add a resource to the top of a resource chain, or to move 
a resource already on the chain to the top of the chain for a specified 
environment. 


When a PC application wants to add a resource to its chain, it should make 


a request to the resource manager. The resource manager then issues the 
Add Resource service to add the resource to the PC environment. 


Register Values 


On Request On Completion 

AH = X‘8E’ CH = X‘13’ 

BL = Options CL = Return code 

DX = ID of the task or X‘0000’ * or DL = Environment ID 
DL = Environment ID or X‘00’ * 

ES = Segment address of the parameter list The contents of registers 
DI = Offset address of the parameter list AX, BX, DH, ES, and DI 


are unpredictable. 


* The value coded in the DX or DL register depends on the value coded in the BL register. 
See “Register Definitions” below for more information. 


Register Definitions 
Request Registers: 
e The BL register indicates the following options: 


— Whether the resource is to be added to the resource chain or moved 
to the top of the resource chain 


— Whether a task ID or an environment ID is to be used to identify 
the environment that requested the Add Resource service from the 
resource manager. 


The format of the options flag is as follows: 


Add resource Must be zero 0 = Environment ID in 
Move resource DL 
1 = Task ID in DX 


0 
1 


e If bit 7 of the BL register is set to 1, the DX register contains the ID of 
the task that requested the Add Resource service from the resource 
manager. If the DX register contains X‘0000’, the environment manager 
uses the ID of the currently executing task. 
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Add Resource 


If bit 7 of the BL register is set to 0, the DL register contains the 
environment ID of the task that requested the Add Resource service 
from the resource manager. If the DL register contains X‘00’, the 
environment manager uses the environment ID of the currently 
executing task. 


The ES register contains the segment address of the parameter list. 


The DI register contains the offset address of the parameter list. 


Completion Registers: 


The DL register contains the ID of the environment to which the 
resource was added or moved. 


Parameter List Format 


Contents Contents 
Offset Length on Request on Completion 
1 word Offset address of Unchanged 
resource 
Segment address Unchanged 
of resource 


4 1 word Reserved Offset address of 
resource chain 


Reserved Segment address 
of resource chain 
ID 


Reserved Reserved 


Parameter Definitions 


Request Parameters: 


The segment and offset addresses of the resource are used as a pointer 
to the resource being added or moved. 


If you are chaining with 1-word pointers, the same segment specified on 
the Identify Resource Manager is always used when that resource 
manager issues an add resource. This is true regardless of the segment 
address that was entered in the parameter list. 


The resource manager ID (returned by the Identify Resource Manager 


service) indicates which resource chain to use to add or move the 
specified resource. 
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Return Codes 


Usage Notes 
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Completion Parameters: 


The segment and offset addresses of the resource chain indicate the 
resource that was at the top of the resource chain before the Add 
Resource service request was completed. If the resource pointer passed 
was the first one on the resource chain, this value is zero. 


The CH and CL registers contain a return code generated by the 
environment manager portion of the workstation program. Environment 
manager return codes use a function ID of X‘13’ (found in the CH register). 
The error codes that can be received are found in the CL register: 


Code Meaning 


X ‘00’ Successful completion. 

X‘05’ Invalid SVC ID. | 

X‘21’ Invalid environment ID. 

XK ‘24’ Invalid resource manager ID. 
X ‘33’ Specified resource not found. 


See Appendix H, “Return Codes,” for more information. 


This service may be requested only by a nonstoppable system extension. 


Before you request the Add Resource service, you must request the 
Identify Resource Manager to identify the resource manager to the 
environment manager. 


When a resource is added to the resource chain, it is always added to 
the top (beginning) of the chain. The resource is assumed to be a data 
area or control block that has as its first field either a 1-word or a 
doubleword pointer. The environment manager uses this pointer field 
to chain together all the resources recorded by the resource manager in 
the specified environment, by setting the pointer field to point to the 
next resource in the resource chain. The environment manager records 
the newly added resource as the first resource in the chain. 


The resource chain enables a resource manager to track the resources it 
has allocated to a particular environment so that it may reclaim those 
resources if a request to stop an environment is received. When a stop 
request is received, each item on the resource chain is sent to the 
resource manager’s cleanup component with an indication that the 
environment is being stopped, reset, or deleted. 


A resource manager can add different “types” of control blocks to its 
resource chain. If it does, the resource control block should contain a 
“type” field so that your resource manager can distinguish between the 
resource “types” when notified of a stop. 


Coding Example 


° 
f 


° 
r 


AROFFSRS 


PARAMETER LIST FOR ADD RESOURCE 


DW O : 
ARSEGRS DW O ; 
AROFFSCH DW 0 ; 
ARSEGCH DW O ; 
ARRMID DB 0 ; 
ARRESRVD DB 0O : 


’ 


‘ 


i 


Add Resource 


OFFSET ADDRESS OF RESOURCE 
SEGMENT ADDRESS OF RESOURCE 
OFFSET ADDRESS OF RESOURCE CHAIN 
SEGMENT ADDRESS OF RESOURCE CHAIN 
RESOURCE MANAGER ID 

RESERVED 


INITIALIZE PARAMETER LIST FOR ADD RESOURCE 


MOV AROFFSRS ,OFFSET RESOURCE 
MOV ARSEGRS ,SEG RESOURCE 

MOV AL,RESMGRID 

MOV ARRMID,AL 


OFFSET ADDRESS OF RESOURCE 
SEGMENT ADDRESS OF RESOURCE 
RESOURCE MANAGER ID 

IN: List 


se Ne Ne Ne 


INITIALIZE REGISTERS FOR ADD RESOURCE 


MOV AH, 8EH 

MOV BL,O1H ; 
MOV -Dx,0 ; 
MOV DI, SEG AROFFSRS ; 
MOV ES,DI ; 
MOV DI,OFFSET AROFFSRS ; 


SIGNAL WORKSTATION PROGRAM FOR ADD 


INT 7AH 
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ADD RESOURCE, AND TASK ID IS IN DX 

USE ID OF THE CURRENT TASK 

SEGMENT ADDRESS OF PARAMETER LIST 
IN ES 

OFFSET OF PARAMETER LIST IN DI 


RESOURCE SERVICE 
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) 


Environment Manager Service X‘8B’: Delete Resource 


Register Values 


Use this service to delete a resource from a resource chain. 


On 


Request On Completion 
= X‘8B’ CH = X‘13’ 
= Options CL = Return code 
= ID of the task or X‘0000’ * or 
= Environment ID or X‘00’ * The contents of registers 
= Segment address of the parameter list AX, BX, DX, ES, and DI 
= Offset address of the parameter list are unpredictable. 


* The value coded in the DX or DL register depends on the value coded in the BL register. 
See “Register Definitions” below for more information. 


Register Definitions 
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Request Registers: 


The BL register indicates whether a task ID or an environment ID is to 
be used to identify the environment that requested the Delete Resource 
service from the resource manager. Possible values of the BL register 
are as follows: 


X‘00’ = Environment ID in the DL register 
X‘01’ = Task ID in the DX register 


If the value of the BL register is X‘01’, the DX register contains the ID 
of the task that requested the Delete Resource service from the resource 
manager. If the DX register contains X‘0000’, the environment manager 
uses the ID of the currently executing task. 


If the value of the BL register is X‘00’, the DL register contains the 
environment ID of the task that requested the Delete Resource service 
from the resource manager. If the DL register contains X‘00’, the 
environment manager uses the environment ID of the currently 
executing task. 


The ES register contains the segment address of the parameter list. 


The DI register contains the offset address of the parameter list. 


Parameter List Format 


Contents Contents 
Offset Length on Request on Completion 
1 word Offset address of Unchanged 
resource 
1 word Segment address Unchanged 
of resource 
1 word Reserved Offset address of 
resource chain 
1 word Reserved Segment address 
of resource chain 
ID 


1 byte 


Parameter Definitions 


Return Codes 
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Delete Resource 


Request Parameters: 


e The segment and offset addresses of the resource are used as a pointer 
to the resource being deleted. 


e The resource manager ID (returned by the Identify Resource Manager 
service) indicates which resource chain to use to delete the specified 
resource. 


Completion Parameters: 


e The segment and offset addresses of the resource chain indicate the 
resource that was at the top of the resource chain before the Delete 
Resource service request was completed. 


The CH and CL registers contain a return code generated by the 
environment manager portion of the workstation program. Environment 

manager return codes use a function ID of X‘13’ (found in the CH register). 
The error codes that can be received are found in the CL register: 


Code 


X‘00’ 
X‘05’ 
X‘21’ 
X ‘24’ 
X‘33’ 


Meaning 


Successful completion. 
Invalid SVC ID. 

Invalid environment ID. 
Invalid resource manager ID. 
Specified resource not found. 


See Appendix H, “Return Codes,” for more information. 
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Delete Resource 


Usage Notes 


Coding Example 


. 
7 


This service may be requested only by a nonstoppable system extension. 


Before you request the Delete Resource service, you must request the 
Identify Resource Manager to identify the resource manager to the 
environment manager, and use the Add Resource service to add 
resources to the resource chain. 


When the last resource is deleted from the resource chain, the 
environment manager will no longer notify the resource manager if the 
environment is stopped, reset, or deleted. 


A resource manager should request this service whenever it removes 
any resources from an environment. The resource manager may choose 
to delete any item —not necessarily the first— on the chain. However, 
on a Stop Environment request, each time the environment manager 
invokes your cleanup component, it will pass the address of one 
resource, traversing in order through the chain starting with the top or 
first item. 


; PARAMETER LIST FOR DELETE RESOURCE 


DROFFSRS DW 
DRSEGRS DW 
DROFFSCH DW 
DRSEGCH DW 
DRRMID DB 
DRRESRVD DB 


oo0o000 


OFFSET ADDRESS OF RESOURCE 
SEGMENT ADDRESS OF RESOURCE 
OFFSET ADDRESS OF RESOURCE CHAIN 
SEGMENT ADDRESS OF RESOURCE CHAIN 
RESOURCE MANAGER ID 

RESERVED 


St ee eT eT eT 


; INITIALIZE PARAMETER LIST FOR DELETE RESOURCE 


MOV 
MOV 
MOV 
MOV 


DROFFSRS ,OFFSET RESOURCE 
DRSEGRS,SEG RESOURCE 
AL,RESMGRID 

DRRMID, 


OFFSET ADDRESS OF RESOURCE 
SEGMENT ADDRESS OF RESOURCE 
RESOURCE MANAGER ID 

IN LIST 


=e Ne we NO 


AL 


; INITIALIZE REGISTERS FOR DELETE RESOURCE 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


AH, 8BH 
BL,O1H 
DX,0 


DI, SEG DROFFSRS 


ES,DI 


DI,OFFSET DROFFSRS 


; TASK ID IN THE DX REGISTER 

; USE ID OF THE CURRENTLY EXECUTING TASK 
; SEGMENT ADDRESS OF PARAMETER LIST 

: IN ES 

; OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR DELETE RESOURCE SERVICE 


INT 
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Query Resource 


Environment Manager Service X‘8C’: Query Resource 


Use this service to obtain the address of the first resource in a specified 
resource chain. 


Register Values 


On Request On Completion 
AH = X‘8C’ CH = X‘13’ 
BL = Options CL = Return code 
CL = Resource manager ID ES = Segment address 
DX = ID of the task or X‘0000’ * or of the resource 
DL = Environment ID or X‘00’ * pointer 

DI = Offset address of 


the resource 
pointer 


The contents of registers 
AX BX, and DX are 
unpredictable. 


* The value coded in the DX or DL register depends on the value coded in the BL register. 
See “Register Definitions” below for more information. 


Register Definitions 
Request Registers: 


e The BL register indicates whether a task ID or an environment ID is to 
be used to identify the task that requested the resource from the 
resource manager. Possible values of the BL register are as follows: 


X‘00’ = Environment ID in the DL register 
X‘01’ = Task ID in the DX register 


e The CL register contains the resource manager ID (returned by the 
Identify Resource Manager service), which indicates which resource 
chain to query. 


e Ifthe value of the BL register is X‘01’, the DX register contains the ID 
of the task that requested the Query Resource service from the resource 
manager. If the DX register contains X‘0000’, the environment manager 
uses the ID of the currently executing task. 


e Ifthe value of the BL register is X‘00’, the DL register contains the 
environment ID of the task that requested the Query Resource service 
from the resource manager. If the DL register contains X‘00’, the 
environment manager uses the environment ID of the currently 
executing task. 
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Completion Registers: 


e The ES register contains the segment address of the resource at the top 
of the resource chain. 


e The DI register contains the offset address of the resource at the top of 
the resource chain. 


Return Codes 


The CH and CL registers contain a return code generated by the 
environment manager portion of the workstation program. Environment 
manager return codes use a function ID of X‘13’ (found in the CH register). 
The error codes that can be received are found in the CL register: 


Code 


X‘00’ 
X‘05’ 
X‘21" 
X‘24’ 


Meaning 


Successful completion. 
Invalid SVC ID. 

Invalid environment ID. 
Invalid resource manager ID. 


See Appendix H, “Return Codes,” for more information. 


Usage Notes 


e This service may be requested only by a nonstoppable system extension. 


e Before you request the Query Resource service, you must request the 
Identify Resource Manager to identify the resource manager to the 
environment manager. 


e If there are no resources on the resource chain, the resource chain 
pointer is zero. 


Coding Example 


; INITIALIZE REGISTERS FOR QUERY RESOURCE 


MOV AH,8CH 
MOV BL,O1H 


MOV CL,MANAGRID 


MOV DX,0 


; TASK ID IN THE DX REGISTER 
; RESOURCE MANAGER ID 
; USE ID OF THE CURRENTLY EXECUTING TASK 


; SIGNAL WORKSTATION PROGRAM FOR QUERY RESOURCE SERVICE 


INT  7AH 
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Suspend/Resume Environment 


Environment Manager Service X‘90’: Suspend/Resume 


Environment 


Use this service to suspend or resume all tasks in the specified 


environment. 
Register Values 
On Request 
AH = X‘90’ 
BH = Reply type 
BL = Wait type 
ES = Segment address of the parameter list 
DI = Offset address of the parameter list 


Register Definitions 


Request Registers: 


On Completion 


AX = Request ID 

BL = Return type 
CH = Function ID 
CL = Return code 


The contents of registers 


BH, DX, ES, and DI 
unpredictable. 


are 


e The BH register specifies the type of reply your application program 
will receive when the request is completed. Possible reply types are as 


follows: 


X‘80’ Request completion is indicated by a ‘completion’ signal. 
Any existing ‘completion’ signal to the application program 


is canceled. 


X‘40’ Request completion is indicated by an RQE on the 
application program’s completion queue. 


X20’ No notification of request completion is received. 


X‘10’ No notification of request completion is received, and the 
parameter list is copied into a 10-byte area, so that the 
parameter list data area can be reused. This is intended for 


interrupt handler usage. 
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Suspend/Resume Environment 


23-18 


/\ 


} 
U 


| 


The BL register specifies the type of wait state your application 
program goes into until the request is completed. The type of wait is 
specified through a bit mask. When more than one type of wait is 
specified, the wait state ends when any one of the conditions is 
satisfied. The bits in the wait type mask are as follows: 


jo ef 
queue queue | signal | phore 


— If bit 0 is set to 1, your application program waits until there is a 
request queue element in its request queue. If there is already an 
RQE in its request queue, the application stays dispatchable. 


— If bit 1 is set to 1, your application program waits until there is a 
request queue element in its completion queue. If there is already 
an RQE in its completion queue, the application stays dispatchable. 


— If bit 2 is set to 1, your application program waits until it receives a 
‘completion’ signal. 


— If bit 3 is set to 1, your application program waits until it receives a 
‘semaphore claimed’ signal. 


— If bit 4 is set to 1, your application program waits until it receives a 
‘timer tick’ signal. 


— If bit 5 is set to 1, your application program waits until it receives a 
‘generic’ signal. 


— If bit 6 is set to 1, your application program waits until it receives a 
‘data available’ signal. 


~— Bit 7 1s reserved and must be set to 0. 


Note: X‘00’ specifies “no wait.” A “wait” for semaphore or data is not 
appropriate for this service. 


e The ES register contains the segment address of the parameter list. 


The DI register contains the offset address of the parameter list. 


Completion Registers: 


The AX register contains the ID of the RQE used by the supervisor for 
this request. 


The BL register indicates the type of wait condition that was satisfied 
to return control to your application program. The return type is | 
specified via a bit mask. The bits in the return type have the same 
meaning as the bits in the wait type. 


Suspend/Resume Environment 


Parameter List Format 


Contents Contents 
Offset Length on Request on Completion 
jot byte | Must be zero [Return code 
1 1 byte Must be zero Function ID 
(X‘13’) 
1 byte Request type Unchanged 
Unchanged 


If using a task ID to specify the environment to be suspended or resumed: 


Contents Contents 
Offset Length on Request on Completion 


Task 1D May be changed 


If using an environment ID to specify the environment to be suspended or 
resumed: 


Contents Contents 
Offset Length on Request on Completion 
1 byte Environment ID May be changed 


Parameter Definitions 
Request Parameters: 


e The request type indicates whether the specified environment is to be 
suspended or resumed as follows: 


X‘05’ — Suspend the environment 
X‘06’ — Resume the environment 


e The flags are as follows: 


Bits 0 — 5 
Must be 0 = All 0 = Env ID used 
1=T 


Zero 1 = All except ask ID used 
requester 
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Bits 0 through 5 are reserved and must be zero. 


Bit 6 indicates whether all tasks in the specified environment are to 
be suspended: 


Bit 6 = 0 — Suspend all tasks in the environment. 
Bit 6 = 1 — Suspend all tasks in the environment except the 
requesting task. 


Bit 7 indicates how the environment to be suspended or resumed is 
specified in the parameter list: . 


Bit 7 = 0 — Environment ID in parameter list 
Bit 7 = 1 — Task ID in parameter list. The task’s environment is the 
one to be suspended or resumed. 


e If bit 7 of the flag byte is 0, byte 4 of the parameter list must contain the 
environment ID of the environment to be suspended or resumed. Byte 5 
of the parameter list is reserved. 


e If bit 7 of the flag byte is 1, word 4 of the parameter list must contain 
the ID of the task whose environment is to be suspended or resumed. 


Return Codes in the CH and CL Registers 
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The CH and CL registers contain a return code generated by the supervisor 
portion of the workstation program or the environment management 
portion of the workstation program. 


Supervisor return codes use a function ID of X‘12’ (found in the CH 
register). The error codes that can be received are: 


Code 


X ‘00’ 
X‘07’ 
X‘0B’ 


Meaning 


Successful completion of the request. 
Invalid reply type specified. 
System RQE pool depleted. 


Environment management return codes use a function ID of X‘13’ (found in 
the CH register). The error codes that can be received are: 


Code 


X00’ 
X‘05’ 
X‘0C’ 
X‘17’ 


X21’ 
X ‘43’ 


Meaning 


Successful completion of the request. 

Invalid task ID. 

Byte 0 of the parameter list was nonzero. 

Stoppable environment cannot stop, reset, suspend, or resume an 
environment other than its own. 

Invalid environment ID. 

Invalid request type (not suspend or resume). 


Suspend/Resume Environment 


Return Codes in the Parameter List 


Usage Notes 


Bytes 0 and 1 of the parameter list contain a return code generated by the 
environment management portion of the workstation program. The 
function ID is in byte 1, and the error code is in byte 0. Environment 
management return codes use a function ID of X‘13’. The error codes that 
can be received are: 


Code Meaning 


X‘00’ Successful completion of the request. 
X‘29” Environment not suspended. 


e A program in a stoppable environment can suspend or resume only its 
own environment. A program in a nonstoppable environment can 
suspend or resume any environment. If a task suspends or resumes its 
own environment, all tasks will be suspended or resumed except for the 
requesting task. 


e When your application or system extension suspends an environment, 
the supervisor sets all the tasks running in that environment to the 
unready state. When you resume, the supervisor sets all the tasks in 
that environment to the ready state. 


e On asuspend request, if a task in the environment holds any code 
serialization semaphores, the suspend processor will wait for the 
semaphores to be released. (Code serialization semaphores are to be 
used to protect I/O operations that cannot be interrupted by a suspend 
or stop request.) A deadlock may occur if the task has gone into a wait 
state while holding the semaphore. A deadlock will certainly occur if 
the task is waiting upon another task in the same environment, since 
all other tasks may be suspended. All application programs should 
observe the semaphore restrictions described in 
Chapter 14, “Supervisor Services.” 


e On asuspend request, any tasks within the environment that are found 
waiting for code serialization semaphores are removed from the 
semaphore wait queue. This prevents other environments from having 
to wait merely because they claim a semaphore allocated to a suspended 
environment. 


e Ona resume request, all tasks waiting on code serialization semaphores 
(that were saved on the suspend request) are restored to the correct 
semaphore wait queues. 


e If an environment holds, or is waiting on, a resource semaphore when it 


is suspended, any environment requesting the semaphore will have to 
wait for the suspended environment to resume. 
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e More than one suspend request can be made for the same environment 
before any resume requests are made. However, an equal number of 
resume requests must be issued before the environment will actually be 
resumed. 


e For the reasons noted above, the Suspend/Resume Environment service 
should be used sparingly. . 


Coding Example 


° 
! 


; PARAMETER LIST FOR SUSPEND/RESUME ENVIRONMENT 


RETURN CODE 

FUNCTION NUMBER 

REQUEST TYPE 

FLAGS 

TASK ID (OR 1-BYTE ENVIRONMENT ID) 


SSRETNCD DB 
SSFXNID DB 
SSTYPE DB 
SSFLAGS DB 
SSTASKID DW 


OoO000 


et Ye TY 


; INITIALIZE PARAMETER LIST FOR SUSPEND/RESUME ENVIRONMENT 


MOV  SSRETNCD,0OH 
MOV  SSFXNID,OOH 
MOV SSTYPE,05H 
MOV  SSFLAGS,03H 
MOV AX,TASKID 
MOV SSTASKID,AX 


RETURN CODE MUST = O BEFORE REQUEST 
FUNCTION ID MUST = O BEFORE REQUEST 
REQUEST TYPE = SUSPEND 

FLAGS = ALL EXCEPT REQUESTER, TASK ID USED 
TASK ID INTO THE LIST 


~e Ne Me Ne Ne 


; INITIALIZE REGISTERS FOR SUSPEND/RESUME ENVIRONMENT 


MOV AH , 90H 

MOV BH, 80H ; REPLY TYPE = COMPLETION SIGNAL 
MOV BL,20H ; WAIT TYPE = COMPLETION SIGNAL 
, 


MOV DI, SEG SSRETNCD SEGMENT ADDRESS OF PARAMETER LIST 
MOV ES,DI IN ES 


MOV DI,OFFSET SSRETNCD OFFSET OF PARAMETER LIST IN DI 
; SIGNAL WORKSTATION PROGRAM FOR SUSPEND/RESUME ENVIRONMENT SERVICE 


INT 7AH 
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Stop/Reset Environment 


Environment Manager Service X‘99’: Stop/Reset 
Environment 


Use this service to stop or reset the specified environment. This service 
corresponds to the Ctrl-Alt-Del key sequence offered by DOS in base PC 
mode. 


e Stopping an environment: 


The stop feature of the Stop/Reset Environment service can be used by 
a system extension to stop all programs that are loaded in a stoppable 
environment. It can also be used by an application to stop the 
environment it is running in. A program running in a stoppable 
environment cannot stop programs running in other stoppable 
environments. 


A stop request asks the environment manager to stop the program(s) in 
the specified environment, releasing any noninitial resources that it 
currently owns, and freeing all storage acquired during its loading and 
execution. It also results in the termination and removal of any 
programs that were loaded and exited but remain resident in the 
environment. On a stop request, the environment’s storage is cleared, 
and any alternate presentation spaces and their associated windows are 
removed. Only the base presentation space and base window remain. 
The environment’s window is cleared, and COMMAND.COM is 
running, waiting for input. 


e Resetting an environment: 


The reset feature of the Stop/Reset Environment service can be used to 
request that an environment’s resources be reset to the state they were 
in when they were first created. For example, all fixed-length queues 
are purged, and all semaphores are released. The environment’s storage 
is not cleared. The environment can reinitialize itself without having 
to be reloaded. All supervisory objects that were created by programs 
running in the environment still exist with the same IDs that were 
assigned to them when they were created. 


This feature is designed for system extensions. For example, system 


extensions that provide communications services from a host session 
that can get a reset from a controller may want to use the reset feature. 


Chapter 23. Coding Environment Manager Services 23-23 


Stop/Reset Environment 


Register Values 


On 


AH 
BH 
BL 
ES 
DI 


Register Definitions 
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Request On Completion 
= X‘99’ AX = Request ID 
= Reply type BL = Return type 
= Wait type CH = Function ID 
= Segment address of the parameter list CL = Return code 
= Offset address of the parameter list 


The contents of registers 
BH, DX, ES, and DI are 
unpredictable. 


Request Registers: 


The BH register specifies the type of reply your application program 
receives when the request is completed. Possible reply types are as 
follows: 


X‘80’ Request completion is indicated by a ‘completion’ signal. 
Any existing ‘completion’ signal to the application program 
is canceled. 


X‘40’ Request completion is indicated by an RQE on the 
application program’s completion queue. 


X‘20’ No notification of request completion is received. 


X‘10’ No notification of request completion is received, and the 
parameter list is copied into a 10-byte area so that the 
parameter list data area can be reused. This is intended for 
interrupt handler usage. 


The BL register specifies the type of wait state your application 
program will go into until the request is completed. The type of wait is 
specified through a bit mask. When more than one type of wait is 
specified, the wait state ends when any one of the conditions is 
satisfied. The bits in the wait type mask are as follows: 


joo fe 
queue queue | signal | phore 


— If bit 0 is set to 1, your application program waits until there is a 
request queue element in its request queue. If there is already an 
RQE in its request queue, the application stays dispatchable. 


— If bit 1 is set to 1, your application program waits until there is a 
request queue element in its completion queue. If there is already 
an RQE in its completion queue, the application stays dispatchable. 


Stop/Reset Environment 


— If bit 2 is set to 1, your application program waits until it receives a 
‘completion’ signal. 


— If bit 3 is set to 1, your application program waits until it receives a 
‘semaphore claimed’ signal. 


— If bit 41s set to 1, your application program waits until it receives a 
‘timer tick’ signal. 


— If bit 5 is set to 1, your application program waits until it receives a 
‘generic’ signal. 


~ If bit 61s set to 1, your application program waits until it receives a 
‘data available’ signal. 


— Bit 7 is reserved and must be set to 0. 


Note: X‘00’ specifies “no wait.” A “wait” for semaphore or data is 
inappropriate for this service. 


e The ES register contains the segment address of the parameter list. 
e The DI register contains the offset address of the parameter list. 
Completion Registers: 


e The AX register contains the ID of the RQE used by the supervisor for 
this request. 


e The BL register indicates the type of wait condition that was satisfied 
to return control to your application program. The return type is 
specified by a bit mask. The bits in the return type have the same 
meaning as the bits in the wait type. 


Parameter List Format 


Contents Contents 
Offset Length on Request on Completion 
fo‘ [ubyte [Must be zero [Return code 
1 1 byte Must be zero Function ID 
(X‘13’) 
1 byte Request type Unchanged 
Unchanged 
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If using a task ID to specify the environment to be stopped: 


Contents Contents 
Offset Length on Request on Completion 


Task ID May be changed 


If using an environment ID to specify the environment to be stopped: 


Contents Contents 
Offset Length on Request on Completion 
1 byte Environment ID May be changed 
1 byte 


Parameter Definitions 
Request Parameters: 


e The request type indicates whether the specified environment is to be 
reset or stopped as follows: 


X‘02’ = Reset the environment 
X‘03’ = Stop the environment 


e The flags are as follows: 


0 = Env ID used 
1 = Task ID used 


— Bits 0 through 6 are reserved and must be zero. 


— Bit 7 indicates how the environment to be stopped or reset is 
specified in the parameter list: 


Bit 7 = 0 — Environment ID in parameter list 
Bit 7 = 1 — Task ID in parameter list. The task’s environment is the 
one to be stopped or reset. 


I 


e If bit 7 of the flag byte is 0, byte 4 of the parameter list must contain the 
environment ID of the environment to be stopped or reset. Byte 5 of the 
parameter list is reserved. 


e Ifbit 7 of the flag byte is 1, word 4 of the parameter list must contain 
the ID of the task whose environment is to be stopped or reset. 
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Stop/Reset Environment 


Return Codes in the CH and CL Registers 


The CH and CL registers contain a return code generated by the supervisor 
portion of the workstation program or the environment management 
portion of the workstation program. 


Supervisor return codes use a function ID of X‘12’ (found in the CH 
register). The error codes that can be received are: 


Code Meaning 


X‘00’ Successful completion of the request. 
X ‘07’ Invalid reply type specified. 
X‘0B’ System RQE pool depleted. 


Environment management return codes use a function ID of X‘13’ (found in 
the CH register). The error codes that can be received are: 


Code Meaning 


X‘00’ Successful completion of the request. 

X‘05’ Invalid SVC ID. 

X‘17’ Stoppable environment cannot stop, reset, suspend, or resume an 
environment other than its own. 

X‘21’ Invalid environment ID. 

X‘32’ The environment is nonstoppable. 


X‘40’ A request to delete the environment using INDSPLIT or 
INDMERGE is already in progress. 
X‘43’ Invalid request type (not stop or reset). 


Return Codes in the Parameter List 


Bytes 0 and 1 of the parameter list contain a return code generated by the 
environment management portion of the workstation program. The 
function ID is in byte 1, and the error code is in byte 0. Environment 
management return codes use a function ID of X‘13’. The error codes that 
can be received are: 


Code Meaning 


X‘00’ Successful completion of the request. 

X‘0C’ Byte 0 of the parameter list was nonzero. 
X‘22’ Some resources were not successfully released. 
X‘OF’ Invalid environment access. 

X‘27° Time-out occurred. 
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A stoppable environment cannot stop an environment other than its 
own. A nonstoppable environment can stop any stoppable environment, 
but it can only reset 1ts own environment. 


If a system extension uses the Make a Request service to send a request 
to a task 1n a stoppable environment, the system extension must be 
aware that the environment can be stopped or deleted at any time. 


If the Make a Request service has been issued, the task in the stoppable 
environment has not started to work on the request, and a stop, reset, 
or delete environment request occurs, the requester’s parameter list is 
returned to the requester with return code X‘1314’. Return code X‘1314’ 
indicates that the work request was not completed, because the 
environment was stopped or deleted before the request could be acted 
on. 


If the suspend request is in process, a stop or reset request waits for the 
suspend request to be completed. 


A stop request asks the environment manager to stop the program(s) in 
the specified environment, releasing any noninitial resources that it 
currently owns and freeing all storage acquired during its load and 
execution. It also results in the termination and removal of any 
programs that were loaded and exited but remain resident in the 
environment. On a stop request, the environment’s storage is cleared, 
and any alternate presentation spaces and their associated windows are 
removed. Only the base presentation space and base window remain. 
The environment’s window is cleared, and COMMAND.COM is 
running, waiting for input. 


After the environment processes the stop request, it is the responsibility 
of the requester to ensure that any initial resources deleted by the 
stopped program are recreated. 


When a stop request is issued, an environment manager task performs 
all supervisor cleanup and will drive all other resource managers for 
cleanup as well. 


To complete cleanup operations, the environment manager task 
prevents initiation of new work by stopping all tasks in the 
environment. It then recovers or waits for completion of all 
outstanding requests. Next, it recovers all resources of external 
resource managers, and finally it recovers its own system resources. 


Stop/Reset Environment 


The system resources that the environment manager task is concerned 
with during cleanup are: 


— Outstanding request queue elements (RQEs) issued by the 
terminating task 


— Semaphores requested by the terminating task 

— Completion RQEs queued to the terminating task 

— Request RQEs queued to the terminating task 

— Logical timers claimed by the terminating task 

— Second-level interrupt handlers created by the terminating task 
— User exit tables created by the terminating task 


— Fixed-length queues created by the terminating task. 


The environment manager ensures that the terminating environment 
cannot do new work by marking all the tasks terminated and unready. 
Those tasks, however, that hold code serialization semaphores will be 
marked pending unready and will be allowed to continue. It is not 
acceptable simply to free the semaphore, as most serialized code 
initiates I/O that should be allowed to complete processing. When the 
semaphore is freed, the environment manager continues with the 
cleanup. 


Note: It is assumed that code serialization semaphores are only claimed 
and released by well-tested code. Therefore, it is assumed that the 
semaphore will be released at some time, and the environment 
manager does not try to force the release of the semaphore. 


The environment manager releases all resource semaphores held by the 
tasks in the environment being stopped. 


RQEs on the completion queue are removed from tasks in the 
environment being stopped. 


The environment manager waits for all accessed RQEs originating from 
each task in the environment being stopped to be released. Accessed 
RQEs are all RQEs from the environment being stopped that were sent 
out to tasks outside that environment, and that a task has already 
started to work on. 


Next, an environment manager task runs through the record of resource 
managers interested in the environment being stopped and issues Make 
a Request services to the resource managers’ cleanup components. The 
environment manager passes a parameter list to the cleanup component 
that contains a pointer to the resource that is to be cleaned up and an 
indication that the environment is being stopped. The format of the 
information sent to the cleanup components is described under the 
heading “The Cleanup Component Interface” on page 23-32. 
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The cleanup component will run under the environment manager task 
at the priority specified on the Identify Resource Manager service 
request. The cleanup component is invoked once for each resource that 
is on the resource manager’s chain for the environment being stopped. 
(Resources are added to a resource chain through the use of the Add 
Resource service.) 


All tasks, fixed-length queues, semaphores, user exit tables, and 
components created by the environment being stopped may be released. 


If any wait state during stop extends beyond a normal! period of time 
(10 seconds), the environment manager sends a return code to the 
requester and displays a return code to indicate to the user that a 
time-out occurred. At this point the user may wish to take some action 
to lighten the system workload, so cleanup operations may be 
completed. However, when an environment has not been fully cleaned 
up, it may be that a serious system error occurred, or that some 
resource manager (or its device) has hung. If a bad return code is 
returned by any of the external resource managers, a return code is 
displayed that indicates some resources were not successfully released. 
In this case, the user may have to take some corrective action. 


After issuing the error message, the workstation program attempts to 
continue cleanup operations. If cleanup operations are eventually 
completed after the user has been notified, the environment manager 
displays a return code that indicates the cleanup operations have been 
completed. At this time, the environment may be reused. 


A reset request asks the environment manager to reset an 
environment’s resources to their state when they were first created. In 
this case only, the environment’s storage is not cleared. The 
environment may now reinitialize itself without having to reload. All 
supervisor resources such as fixed-length queues and tasks still exist, 
with the same IDs assigned to them by the supervisor when they were 
created. 


A task can only do a reset for its own environment. 


Reset processing is similar to stop processing in that the environment 
manager will mark all tasks in the environment being reset as 
terminating and unready. Those tasks that hold code serialization 
semaphores are allowed to continue until the semaphores are released. 


The environment manager then releases all resource semaphores held 
by the tasks in the environment being reset. 


Stop/Reset Environment 


All hardware and software second-level interrupt handlers belonging to 
the environment being reset are left as they were. All timers belonging 
to the environment are stopped. Request queue elements (RQEs) on the 
completion queue are removed from tasks in the environment being 
reset. RQEs going to other tasks in the system are removed. As during 
stop processing, the environment manager waits for all accessed RQEs 
to be freed. All RQEs coming into the tasks in the environment being 
reset are returned to the requester with error code X‘1314’. 
Fixed-length queues are purged. 


The environment manager notifies all resource managers interested in 
the environment that the environment is being reset. The format of the 
information sent to the resource manager is described under the 
heading “The Cleanup Component Interface” on page 23-32. 


Tasks are marked as nonterminating when the reset has been completed 
by the environment manager. 


Only the task that initially requested the reset is set ready. It is 
recommended that the requesting task use the Create Task Entry 
service with the reset option for all other tasks in the environment. 
This will reset each task state to what it was when it was originally 
created. The requesting task must then set ready other tasks in the 
environment. 


If an application program uses the Make a Request service to send a 
request to a task in a system extension that can be reset, the 
application program must be aware that the system extension’s 
environment can be reset at any time. 


If the Make a Request service has been invoked, the task in the system 
extension has not started to work on the request, and a reset request 
occurs, the requester’s parameter list is returned to the requester with a 
return code of X‘1314’. This code indicates that the request was not 
completed, because the environment was reset before the request could 
be acted on. 
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When an environment is stopped, reset, or deleted, the environment 
manager sends a Make a Request service to the cleanup component of each 
resource manager that was interested in the environment for each of its 
resources on the chain. The Make a Request service sends information to 
the cleanup component in the following format: 


fo _[1tyte [Return code ——SSCS~*d 
ec 
7 


1 byte Environment ID 
7s A byte 


e The offset and segment address of the resource is a resource that was 
added to the resource manager’s resource chain through the use of the 
Add Resource service. Each time the environment manager invokes 
your cleanup component, it will pass the address of one resource, 
traversing in order through the chain, starting with the top of the 
resource chain. 


e The environment ID is the ID of the environment being reset, stopped, 
or deleted. 


e The Action indicates whether the environment is being reset or stopped 
as follows: 


X‘02’ = Reset 
X‘03’ or X‘04’ = Stopped 


The above information is sent to the cleanup component for each 
resource on the resource manager’s chain whenever an environment 
that has resources allocated by this resource manager is reset, stopped, 
or deleted. The cleanup component will run under an environment 
manager task at the priority specified for it on the Identify Resource 
Manager service request. This allows a resource manager to clean up 
any resources it may have allocated at an application’s request when an 
environment is reset, stopped, or deleted. It is the resource manager’s 
responsibility to issue the Delete Resource request as necessary to 
remove resources it has cleaned up from the stopping environment. 


If the cleanup component is unable to release all resources or detects an 
error, it must set a nonzero value in the return code portion of the 
parameter list. See the heading “System Extension Return Codes” in 
Chapter 24, “Coding System Extensions,” for more information. 


Stop/Reset Environment 


Coding Example 


; PARAMETER LIST FOR STOP/RESET ENVIRONMENT 


RETURN CODE 

FUNCTION NUMBER 

REQUEST TYPE 

FLAGS 

TASK ID (OR 1 BYTE ENV. ID) 


STRETNCD DB 
STFXNID DB 
STTYPE DB 
STFLAGS DB 
STTASKID DW 


OOO0O00 


et eT ey eT 


e 
f 


; INITIALIZE PARAMETER LIST FOR STOP/RESET ENVIRONMENT 


MOV STRETNCD,OOH 
MOV STFXNID,OOH 
MOV STTYPE,03H 
MOV STFLAGS,O1H 
MOV AX,TASKID 
MOV STTASKID,AX 


RETURN CODE MUST = O BEFORE REQUEST 
FUNCTION ID MUST = O BEFORE REQUEST 
REQUEST TYPE = STOP , 

FLAGS = TASK ID USED 

TASK ID INTO THE LIST 


Ne Se Ne Ne Ne 


; INITIALIZE REGISTERS FOR STOP/RESET ENVIRONMENT 


MOV AH , 99H 

MOV BH, 80H ; REPLY TYPE = COMPLETION SIGNAL 
MOV BL,20H ; WAIT TYPE = COMPLETION SIGNAL 

MOV DI, SEG STRETNCD ; SEGMENT ADDRESS OF PARAMETER LIST 
MOV ES,DI ; IN ES 

MOV DI,OFFSET STRETNCD ; OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR STOP/RESET ENVIRONMENT SERVICE 


INT 7AH 
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Environment Manager Service X‘11’: Query Task’s 
Environment ID 


Use this service to obtain the environment ID associated with a specified 


task. 
Register Values 
On Request On Completion 
AH = X11’ CH = X‘12’ or X‘13’ 
DX = Task ID or X‘0000’ CL = Return code 
DL = Environment ID 


The contents of registers 
AX, BX, DH, ES, and DI 
are unpredictable. 


Register Definitions 
Request Registers: 
e The DX register contains the ID of the task being queried. If the DX 
register contains X‘0000’, the environment manager uses the ID of the 
currently executing task. 


Completion Registers: 


e The DL register contains the environment ID associated with the 
specified task. 


Return Codes 


The CH and CL registers contain a return code generated by either the 
supervisor or environment manager portion of the workstation program. 


e Supervisor Return Code: 
The supervisor return code uses a function ID of X‘12’ (found in the CH 
register). The error code that can be received is found in the CL 
register: 


Code Meaning 


X‘05’ Invalid SVC ID. 
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e Environment Manager Return Codes: 


Environment manager return codes use a function ID of X‘13’ (found in 
the CH register). The error codes that can be received are found in the 
CL register: 


Code Meaning 


X‘00’ Successful completion. 
X‘05’ The specified SVC ID is not a task. 


See Appendix H, “Return Codes,” for more information. 


Usage Notes 


A system extension or application can use this service to determine which 
environment issued a particular request. If the system extension or 
application is a task, this is the task to which completion status must be 
posted. If it is a component, the task is the one the component is currently 
running under. 


Coding Example 


; INITIALIZE REGISTERS FOR QUERY TASK'S ENVIRONMENT ID 


MOV AH,11H 
MOV DX,0 ; USE ID OF THE CURRENTLY EXECUTING TASK 


; 
; SIGNAL WORKSTATION PROGRAM FOR QUERY TASK'S ENVIRONMENT ID SERVICE 


INT 7AH 
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Environment Manager Service X‘8D’: Query 
Environment Characteristics 


Use this service to obtain a list of characteristics associated with a 
specified environment. The characteristics obtained indicate whether the 
environment is: 


Register Values 


On 


Stoppable or nonstoppable 
A user environment or a system environment 


Allocated or available for use. 


Request On Completion 
= X‘8D’ BH = Number of 
= Options flag environments 
= Output buffer length CH = X‘13’ 
= ID of the task or X‘0000’ * or CL = Return code 
= Environment ID or X‘FF’ * 
= Segment address of the output buffer The contents of registers 
= Offset address of the output buffer AX, BL, DX, ES, and DI 


are unpredictable. 


* The value coded in the DX or DL register depends on the value coded in the BL register. 
See “Register Definitions” below for more information. 


Register Definitions 
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Request Registers: 


The BL register indicates whether a task ID or an environment ID is to 
be used to identify the environment being queried. Possible values of 
the BL register are as follows: 


I 


X‘00’ Environment ID in the DL register 
X‘01’ = Task ID in the DX register 


The CX register contains the number of bytes in the output buffer, 
which will contain the environment characteristics on completion of the 
request. If the value in the CX register is zero, the total number of 
environments in the system is returned in the BH register. 


If the value of the BL register is X‘01’, the DX register contains the ID 
of a task in the environment being queried. If the DX register contains 
X‘0000’, the environment manager uses the ID of the currently 
executing task. 


Query Environment Characteristics 


e Ifthe value of the BL register is X‘00’, the DL register contains the ID 
‘of the environment being queried. If the DL register contains X‘00’, the 
environment manager uses the ID of the currently executing task to 
identify the environment being queried. If the DL register contains 
X‘FF’, the environment manager returns the characteristics of all 
environments. 


e The ES register contains the segment address of the output buffer. 
e The DI register contains the offset address of the output buffer. 
Completion Registers: 


e The BH register contains the number of environment descriptions 
returned. 


The BH register will contain the total number of environments in the 
system in the following cases: 


— Ifinformation was requested for all environments and the buffer 
was not large enough for the information 


— Ifinformation was requested for one environment and the buffer 
was not large enough for the information 


— Ifthe CX register contains zero on request. 


In these circumstances, only the request for information on all 
environments returns an unsuccessful return code if there is not enough 
room in the output buffer. 


Output Buffer Format 


The environment information is returned in a variable-length buffer area 
that your application program must provide. In the format of the output 
buffer, offsets of 0 and 1 as shown below must be repeated for as many 
environments as can be returned for the request. 


| Contents Contents 
Offset Length on Request on Completion 


1 byte Environment ID 
Reserved Environment 
characteristics 


* The environment ID is the ID of the environment whose characteristics are given in 
the following byte. 
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The environment characteristics are indicated by the following bit settings: 


Nonstoppable 


ea = Available Reserved 
= In use 


= Stoppable 


The CH and CL registers contain a return code generated by the 
environment manager portion of the workstation program. Environment 
manager return codes use a function ID of X‘13’ (found in the CH register). 
The error codes that can be received are found in the CL register: 


Code Meaning 


X‘00’ Successful completion. 

X‘05’ Invalid SVC ID. 

X‘21’ Invalid environment ID. 

X‘28’ The output buffer is too small. 


See Appendix H, “Return Codes,” for more information. 


; INITIALIZE REGISTERS FOR QUERY ENVIRONMENT CHARACTERISTICS 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


DI, SEG OUTBUFF 
ES ,DI 
DI,OFFSET OUTBUFF 


° 
, 
’ 
° 
‘ 
° 
’ 
° 
‘ 
e 
cf 


TASK ID IN THE DX REGISTER 
SIZE OF BUFFER AREA 
USE ID OF THE CURRENTLY EXECUTING TASK 
SEGMENT ADDRESS OF BUFFER AREA 
IN ES 
OFFSET OF BUFFER AREA IN DI 


; SIGNAL WORKSTATION PROGRAM FOR QUERY ENVIRONMENT CHARACTERISTICS 


SERVICE 


. 
, 


INT 


7AH 


Query Environment Characteristics 
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Introduction 
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You can code a system extension that will run as part of the workstation 
program. System extensions must be well-behaved. The system extension 
runs in its own nonstoppable environment, created by the DOS subsystem 
when the system extension is loaded into memory. System extensions do 
not have a logical screen or keyboard. A system extension should not write 
to the display buffer or accept input from the keyboard unless it has used 
the API to establish a presentation space or keyboard definition. System 
extensions should provide services to other programs in stoppable 
environments and to tasks or system extensions in nonstoppable 
environments. 


A system extension has greater flexibility than normal application 
programs because it runs in a nonstoppable environment. System 
extensions are a permanent part of the system and cannot be removed until 
the system unit is turned off or re-[PLed. System extensions must follow 
the guidelines described in Chapter 2, “Programming Considerations.” 
Considerations for system extensions that will act as resource managers are 
described in Chapter 22, “Environments and the Environment Manager.” 


When system extensions create parameter lists to pass data between tasks 
and components, they should reserve the first word of the parameter list for 
the return code. 


Notes: 
1. Some languages are by nature poorly behaved and should not be used. 


2. In XMA systems, application spaces are not all addressed 
simultaneously. If system extensions process parameter lists from PC 
applications, they should process them when they receive the request 
(because, at that time, they will be running in the PC’s bank). If the 
system extensions put the parameter list on a work queue, and on a 
subsequent redispatch they process the work queue, the system extensions 
will not be in the correct bank to be looking at the user’s parameter list. 


3. System extensions should use the Enqueue Data service and Dequeue 
Data service to enqueue and dequeue data. These services are not 
recommended for passing parameter lists from one task to another. 
Assume a PC application in an XMA environment enqueues a parameter 
list to a user system extension, when the user system extension was given 
control after a Dequeue Data service, the system extension would not be 
running in the bank of the PC application and, thus, could not look at the 
user’s parameter list. 


Create a System Extension 


How to Create a System Extension 


A system extension can be either a DOS format .EXE file or a DOS format 
.COM file. Typically, a system extension consists of three parts: 


1. Resident code 
2. Fixed data 
3. Initialization code. 


By keeping the initialization code separate from the resident code, it is 
possible to make the storage occupied by the one-time initialization code 
available for other system extensions or DOS environments. 


Following is a source code example of a .COM file. The initialization code 
is separate from both the resident code and the data. 


START JMP INITCODE 
RESIDENT CODE 
e 
e 
e 
FIXED DATA 
e 
a 
e 
INITCODE: 
INITIALIZATION CODE 


RETURN TO DOS VIA INTERRUPT X'21' 
AND FUNCTION CODE X'31'. 


Resident Code 


The resident code part of the system extension should include the code to 
be run when tasks or components are invoked. 


Note: If your system extension is going to use DOS function calls, it is 
recommended that you use the API DOS function request so that the 
function does not use the interrupt vectors to issue the request, 
allowing poorly behaved applications to run simultaneously. 


Chapter 24. Coding System Extensions 24-3 


Create a System Extension 


Fixed Data 


The fixed data part of the system extension should include any data 
declarations and data structures needed by the system extension. 


Initialization Code 


The initialization code part of the system extension should create all the 
system objects (such as tasks, components, or queues) needed by the system 
extension. The initialization code should also request the Set Task Ready 
service for all tasks that need to be started at that time. The initial task 
that the initialization code is running under will be deleted when the 


initialization of the system extension is completed. 


If the system extension needs to allocate any variable or dynamic data, it 
can do so by having the initialization code relocate itself to the high end of 
storage. Once relocated, the initialization code can create control blocks 
and data areas in the area of storage where it used to reside. There are 
several advantages to this approach, since the data areas can be in the 
same segment of storage as the original data areas. This approach results 
in better performance, since the data areas can be accessed by the offset 
address only, instead of both the segment and offset addresses. Another 
advantage to this approach is that the number of control blocks can be 
determined from the configuration information. It is also generally faster 


to build control blocks, rather than read them in from a disk. 


Following is an example of initialization code written to move itself to the 


high end of memory and execute there. 


AAA: PROC FAR 


MOV ES, TOADR 
SUB DI,DI 

SUB ST,S1 

MOV CX ,MODSIZE 
CLD 
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se se NO “ee Ne Ne MO Ne NO 


=e Se NO UNO 


ES-DI IS THE ADDRESS YOU ARE 
RELOCATING THE CODE TO. TOADR 
IS FOUND BY SUBTRACTING THE SIZE 
OF THE MODULE IN PARAGRAPHS FROM 
THE TOP OF STORAGE, WHICH IS 
FOUND IN THE PSP 


DS-SI IS THE ADDRESS YOU ARE 
RELOCATING THE CODE FROM. THE 
DS REGISTER IS SET UP ON ENTRY. 


MODSIZE IS THE SIZE OF THE 
MODULE IN WORDS (USING WORDS 
FOR THE SIZE IS FASTER THAN 
USING BYTES) 


System Extensions 


REP MOVS WORD PTR[DI],WORD PTR[ST] ; MOVE TO HIGH STORAGE 
PUSH ES ; SET UP THE STACK TO DO A FAR 
LEA BX, RELOCAT ; RETURN AND GIVE CONTROL TO 
PUSH . BX ; LABEL RELOCAT 


RELOCAT: 


AT THIS POINT YOU ARE RUNNING 
CODE RESIDING AT THE HIGH END OF MEMORY 


Se eT Ty 


After the initialization code is completed, a system extension should return 
to DOS by using interrupt 21H with function code X‘31’. This function 
allows you to tell DOS the number of paragraphs to keep resident, thus 
allowing the initialization code storage to be reused. (See note 3 under 
Panel 8.1 later in this chapter.) 


How to Tell the Workstation Program about Your 
System Extension 


In order to tell the workstation program that your system extension exists, 
you must: 


e Supply information in the customization process 


e Create a SIF for the extension. 


Customization Procedure 


You tell the workstation program to load user-supplied system extensions 
through the customization process. This process is described in the JBM 
3270 Workstation Program User’s Guide and Reference manual. A system 
extension can be added to or removed from the system only by customizing. 


On the following customization home panel there is a question asking you 
for the number of user-supplied system extensions to be included in the 
workstation program. Enter the number of user-supplied system extensions 
you have written. 
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Home panel IBM CORPORATION 
3270 WORKSTATION CUSTOMIZATION 


Level 1.00 Copyright IBM Corp. 1984, 1987 


Move cursor under the desired option. 
Press PF2 to select, or type the required information 


DEFAULTS IBM-supplied default values 
Drive from which previously customized 
system values are read 

TARGET Drive to which customized system is written 


XMA CARD The expanded memory adapter card is installed 


STORAGE Amount of storage on XMA card 
(1 - 2 M) 


SYSTEM Number of user-supplied system extensions 
EXTENSIONS (0-29) 


PF1=Help PgDn=Next End=Summary Esc=Quit 
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System Extensions 


Later in the customization process, Panel 8.1 (shown below) asks you to 
enter data about your system extensions. At this time you can specify 
which drive the system extension module will be loaded from. You can 
choose to put your system extension on the customized system diskette, on 
a different diskette, or on the hard disk. For information on entering data 
in panel 8.1, see the IBM 3270 Workstation Program User’s Guide and 
Reference manual. 


Panel 8.1 USER-SUPPLIED SYSTEM EXTENSION OPTIONS 


Move cursor under the desired option. 
Press PF2 to select, or type the required information. 


Customized system is 375K allocated, XXXXK free 
NAME 2 Name of system extension 


STORAGE a Storage required for system extension 


DOS System extension uses DOS functions 


DEFAULT Default disk drive for this extension 


DEFAULT DIRECTORY 


PFl=Help PgDn=Next PgUp=Prev Home=Home End=Summary Esc=Quit 


The following list explains the User-Supplied System Extension Options: 


1. If your system extension uses DOS function calls, you should reply 
“yes” to DOS and the Multi-DOS feature will be selected for you. 
Multi-DOS = yes will protect you from the PC application and the 
system extension doing a file I/O at the same time. (This combination 
causes problems.) If you choose not to select the Multi-DOS feature, 
then you must protect yourself from the PC and system extension doing 
file I/O at the same time. (For example, assume your reply is DOS=no, 
even if your system extension uses DOS. The PC application can issue 
the Make Request service to the system extension with a WAIT option. 
The system extension will do all DOS functions and not reply to the PC 
application until all DOS functions complete processing.) If your 
system extensions use DOS function calls only during initialization, you 
can answer DOS=no. | 


Again, DOS is not reentrant and can handle function calls only on a 
serial basis. The Multi-DOS feature ensures that DOS gets all requests 
serially. Without the Multi-DOS feature, the application and system 
extension must ensure that DOS gets all function requests serially. 
Your indication on Panel 8.1 that your system extension uses DOS will 
automatically select the Multi-DOS feature. 
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If a PC application takes over interrupt X‘21’, then system extensions 
must use the DOS asynchronous service (discussed in 

Chapter 138, “Coding Multi-DOS Support Service Requests”) to make all 
DOS interrupt X‘21’ function calls. This ensures that DOS gets your 
request and not the application that took over interrupt X‘21’. (This 
action is available only if the Multi-DOS feature is selected at 
customization time.) 


If your system is running Multi-DOS and it takes over interrupts, it 
must use the Install a Hardware Interrupt Handler service or Install an 
Interrupt Handler service to do so. If it uses DOS to take over the 
interrupts, only the environment that used DOS to take over the 
interrupt will see the interrupt. System extensions run in their own 
environment. PC applications run in different environments. If an 
application is running and causes a software interrupt that is taken 
over by a system extension using DOS calls, the handler installed by the 
system extension will not get control. It would detect a 000 vector. 


If your system extension is running without the Multi-DOS feature, 
then DOS can be used to take over interrupts without any problems. 
(The supervisor API will also work without problems.) 


Storage Required: 


a. Ifyou reply “yes” to using DOS, the storage size is the size of your 
system extension .COM or .EXE file (including initialization code), 
plus 4K bytes for DOS control blocks, plus the size of any variable 
data allocated by the system extension. The specified storage size is 
actually allocated by the workstation program for this system 
extension. When initialization code is completed, it should issue 
DOS interrupt X‘21’ and function code X‘31’ to terminate and stay 
resident, and to specify the number of paragraphs to remain 
resident. This frees storage to be used only by the system extension. 
This extra storage is not available to the system or DOS. 


b. If your system extension replies “no” to using DOS, the storage size 
is the size of your system extension .COM or .EXE file (including 
initialization) plus the size of any variable data allocated by your 
system extension (if applicable). / 


In this case, storage is not actually allocated by the workstation 
program for this system extension. The system extension is simply 
loaded by DOS, and initialization is run. When it is completed, it 
issues the DOS function call to terminate and stay resident, 
specifying the number of paragraphs to remain resident. This frees 
storage to be used by the entire system and DOS. 


System Extensions 


Creating and Modifying System Information Files (SIFs) 


You use the INDSPIF utility to create and modify SIFs. The INDSPIF 
utility is provided on your 3270 Workstation program diskettes. 


To use the INDSPIF utility, follow these steps: 


_ 1. Determine the name of the EXE or COM file you will use. This will be 
the name of the SIF file. 


2. For system extensions, determine how many of each type of control 
block are needed for the system extension to run. 


3. At the DOS prompt, enter the INDSPIF command by typing INDSPIF 
followed by the Enter key. 


4, On the Home panel, you may enter the module name or the path name. 
a. To create a System Information File, press PF2. 
b. To read an existing System Information File, press PF3. 

5. Depending on your shoice you will see the SIF panel. 


6. Complete all items on the panel. When you are done, press PF3 to save 
the SIF on diskette. 


7. You may then press either Home, to return to the Home panel, or Esc, 


to quit the INDSPIF utility, or you may change any information on the 
panel and save it again. 
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How to Determine the Numbers to Use for Your System Information File 


The panel that must be completed to create a SIF for a system extension is 
as follows: 


Panel 1 of 1 SYSTEM INFORMATION FILE OPTIONS 
Type the required information. 

PROGRAM NAME: 
DIRECTORY: C% 


ECB 
RESM 
TCB 
ROE 
GATE 
NAME 
SVC 
SLIH 
TIMER 
STACK 


How many Environment Control Blocks? 

How many Resource Managers? 

How many Task Control Blocks? 

How many Request Queue Entries? 

How many Gate Entries? 

How many Name Table Entries? 

How many SVC Entries? 

How many Second Level Interrupt Handlers? 
How many Logical Timers? 

How many Stacks for the FLIH? 


OOOCTOD0O0000 YY 


Press PF3 to write the System Information File. 


PF3=Write Home=Home Panel Esc=Quit 


The following list explains each System Extension Option and how to 
determine what number to enter on the panel. 


1. ECB: Environment Control Blocks 


This is the environment your system extension will be running in. This 
number must be set to 1, since each user system extension runs in its 
own environment. Do not change this number. 


2. RESM: Resource Managers 


This is the number of resource managers created by your system 
extension. A resource manager is created by an Identify Resource 
Manager service request. Determine the maximum number of Identify 
Resource Manager service requests your code issues and enter this 
number in the RESM field. 


3. TCB: Task Control Blocks 
This is the number of tasks created by your system extension. A TCB is 
created by a Create Task Entry service request. Determine the number 


of Create Task Entry service requests your code issues and enter this 
number in the TCB field. 
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RQE: Request Queue Entries 


This is an estimate of the number of request queue entries likely to be 
used by the system extension at any given time. Every time your code 
issues one of the following, at least one RQE is used and later returned 
to the free pool: 


a. The Make a Request service (one RQE) 


b. A Make a Request service with a reply type of X‘10’ (no notification 
of request completion, copy parameter list) (two RQEs) 


c. The Claim Semaphore service (one RQE) 
d. The Dequeue Data service (one RQE) 
e. All of the following service requests use one RQE each: 


1) Session information services 

2) Keyboard services 

3) Window management services 

4) Host interactive services 

5) Presentation space services 

6) 3270 keystroke emulation services 
7) Copy services 

8) Translate service 

9) Operator information area services 
10) Multiple DOS services 

11) The Stop Environment service 

12) The Suspend Environment service 


Determine the maximum number of these service requests that may be 
pending at any time. Enter this value in the RQE field. 


GATE: Gate Entries 


This is the total number of gate service entries put in the gate table by 
your module. For example, if five gates are created, each with two gate 
service entries, then 10 is the number you specify for this System 
Extension Option. A gate is created by a Create Gate Entry service 
request. Add up the number of service entries you specify on each 
Create Gate Entry service request your code will issue. Enter this 
number in the GATE field. 


NAME: Name Table Entries 


This is the number of names put in the name table by your module. A 
name is created every time you issue a supervisory object service 
request that uses the name option to assign a name to the object. Add 
up all the supervisory object service requests that your system 
extension issues with the name option and enter this number in the 
NAME field. 
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7. 


10. 


For 


SVC: Services 


This is the total number of entries put into the SVC table by your 
module. The following items take an entry in the SVC table: 


a. Tasks 

b. Components 

ce. Fixed-Length Queues 

d. User Exit Tables 

e. . Gates (not the entries in the gate table, but the actual gates) 


f. Semaphores 


To determine this value, add up all the Create Task Entry, Create 
Component Entry, Create Semaphore Entry, Create Fixed-Length Queue 
Entry, Create User Exit Table Entry, and Create Gate Entry service 
requests your system extension will issue. Enter that value in the SVC 
field. 


SLIH: Second-Level Interrupt Handlers 


This is the number of unique second-level interrupt handlers installed 
by your module. A second-level interrupt handler is created every time 
you request the Install a Hardware Interrupt Handler service or the 
Install an Interrupt Handler service. Determine the maximum number 
of these requests your code will issue and enter this number in the 
SLIH field. 


TIMER: Logical Timers 


This is the number of logical timers created by your module. A TIMER 
is created every time you issue a Get Logical Timer service request. 
Determine the maximum number of Get Logical Timer service requests 
your code will issue and enter this number in the TIMER field. 


STACKS: 


Note: You should ignore this field unless you are updating 
INDIBM2.SIF. 


For systems that have an XMA card installed, you may want to specify 
one or more STACKS. You must do so if your PC applications install 
interrupt handlers that swap stacks and then enable. The STACK field 
will not be multiplied by the number of PC sessions you have 
customized for. 


Note: You should not increase this field unless absolutely necessary, 
since it allocates large areas of storage for stack use. 


more information on using the SPIF facility to create SIFs, see JBM 


8270 Workstation Program User’s Guide and Reference. 
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Loading a System Extension 


How a System Extension Is Loaded 


After you complete the customization process, you will have a customized 
diskette that you can use to IPL the workstation program. When you IPL 
the workstation program, the DOS loader loads all the system extensions 
from low storage to high storage. 


The DOS loader reads the configuration file that was produced by 
customization (INDCFIG.DAT) and loads the system extensions that were 
specified in the file. User-supplied system extensions are loaded after the 
workstation program system extensions, but before the remaining storage is 
divided among the personal computer environments. If you are using the 
XMA card, the loader will find a place to install your system extension. 
This may be anywhere in the 1-megabyte address space of the PC. 


The system extension is loaded and started the same way that DOS is 
loaded, as follows: 


e The system extension is loaded in storage, and control is passed to the 
entry point of the initialization code. 


e Both the ES and DS registers contain the segment address of the 
program segment prefix (PSP), and the offset is always zero. Refer to 
the DOS Technical Reference manual for the format of the PSP. 


e The amount of memory available to the system extension is recorded in 
its program segment prefix. 


The location PSP + X‘82’ will contain the address of the entry within the 
configuration file that describes the system extension being loaded. The 
first two bytes of the entry are used as a return code when control is passed 
back to the DOS loader after initialization is completed. The 2-byte return 
code is made up of a 1-byte function code and a 1-byte error number. If the 
error code is nonzero, message ST004 will be issued by the DOS loader and 
will contain the system extension name, the return code, and an option to 
take a dump or continue bringing up the system. 


It is recommended that system extensions use this return code in the event 
that initialization fails. For more information about the return codes that 
your system extension can use, see “System Extension Messages and Return 
Codes” on page 24-15. 
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640K 


+0 


The following diagram shows storage allocation as system extensions are 
loaded into memory. 


Step 1 illustrates a system extension loaded into low memory with resident 
code separate from initialization code. The initialization code gets control 
to execute first. 


Step 2 illustrates a system extension relocating its initialization code to the 
high end of storage. The initialization code runs in high storage, allocating 
variable data as an extension of the fixed data. When the initialization 
code is completed, the system extension will return to DOS. The return to 
DOS causes only the resident code and the fixed and variable data to 
remain in the system. In effect, the initialization code is deleted from the 


system. 


Step 3 illustrates storage allocation after all system extensions have been 
loaded, the initialization code has been run and deleted from the system, 
variable data has been allocated, and the personal computer environments 
have been allocated. 


DOS Loader 


System extension 1 
initialization code 


Data portion of system 
extension 1 


Code portion of system 
extension | 


3270 PC Control Program 


Step 1 
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DOS Loader 


System extension 1 
initialization code relocated 


Variable data 
Data portion of system 
extension 1 


Code portion of system 
extension | 


3270 PC Control Program 
+0 


Step 2 


640K 


DOS environment 3 
DOS environment 2 
DOS environment 1 


System extension n 


System extension 3 


System extension 2 
Variable data 


Data portion of system 
extension 1 


Code portion of system 
extension | 


3270 PC Control Program 


Step 3 
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System Extension Messages and Return Codes 


Your system extension may want to issue messages to the terminal user to 
inform him of a normal] event that is happening in the system or to tell him 
of an error that occurred while the system extension was running. 


A system extension can issue messages by using the System Extension 
Message API service. This service supports error messages with three 
possible levels of severity, and also supports informational messages. The 
error messages that can be issued allow you to include a return code at the 
end of the message. All messages are displayed on the bottom of the screen 
in reverse video. The System Extension Message service is described under 
the heading “The System Extension Message Service.” 


It is recommended that all messages issued by the system extension start 
with a unique identifier. 


System Extension Return Codes 


The workstation program uses a standard format for return codes. Return 
codes are 2 bytes long. The first byte is a function ID, and the second byte 
is an error code. The function ID indicates the portion of the workstation 
program in which the error occurred. The error code indicates the specific 
type of error that has occurred. 


The workstation program has reserved the following function IDs for use by 
system extensions: 


e X‘Dx’ = Vendor-supplied system extensions 


e X‘Ex’ = User-supplied system extensions 


e X‘Fx’ 


I 


IBM-supplied system extensions 
where x is the ID of the environment that the system extension 1s running 
in. The environment ID can be obtained by requesting the Query 


Environment ID service. 


The error code can be any number from 0 to 255. An error code of X‘00’ 
always indicates a successful acceptance or completion of the request. 
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The System Extension Message Service 


You can use the System Extension Message service to do the following: 


1. Identify the error return codes that will be used by the system extension 
as part of message INDSY001, INDSY002, or INDSY003 


2. Issue error message INDSY001, INDSY002, or INDSY003 

3. Issue informational messages written by the system extension. 

Each of these functions is described in the following sections. 

Note: The System Extension Message service is available for use by system. 


extensions only, not by application programs running in stoppable 
environments. 


Identifying Error Return Codes with the System Extension Message Service 


Each return code that can be issued by your system extension as part of 
message INDSY001, INDSY002, or INDSY003 must be identified to the error 
handler portion of the workstation program before it can be displayed using 
the System Extension Message service. This needs to be done only once for 
each system extension, so that it is recommended that it be done in 
initialization code. When you identify a return code to the error handler, 
you provide the following information: 


e The function ID and error code of the return code 
e The threshold value for the error message 
e The severity level of the error message. 


The function ID and the error number must conform to the standard 
described under the heading “System Extension Return Codes” above. 


The threshold value for the error message indicates the number of times the 
error can occur before an action is taken by the error service. 


The severity level of the error message identifies the message that will be 
displayed when the error threshold is reached. There are three levels of 
error severity, as described below: 


e Severity 1: A severity 1 error is an unrecoverable system error. The 
message that is displayed is INDSY001. The user can either press D to 
take a dump or press any other key to re-IPL the system. 


e Severity 2: A severity 2 error is a less serious error. The message that 
is displayed is INDSY002. The user can either press D to take a dump 
or press any other key to continue. 


e Severity 3: A severity 3 error is a minor error. The message that is 
displayed is INDSY003. The system continues running after the user 
presses another key. 
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Requesting Error Messages with the System Extension Message Service 


Your system extension can request the System Extension Message service 
to display error message INDSY001, INDSY002, or INDSY003 in the event 
of an error, along with a 2-byte return code and, optionally, 2 bytes of data. 
The error message is displayed when the threshold level associated with the 
return code has been reached. 


e Severity 1 errors: 


When the System Extension Message service is requested for a severity 
1 error and the threshold associated with the error is reached, the 
following message is displayed: 


INDSYOO1 Unrecoverable system error - xxxxxxxx Press D to 
take a dump or any other key to Re-IPL 


e Severity 2 errors: 


When the System Extension Message service is invoked for a severity 2 
error and the threshold associated with the error is reached, the 
following message is displayed: 


INDSYOO2 Component error - xXxxxxxxx Press D to take a 
dump or any other key to continue 


e Severity 3 errors: 


When the System Extension Message service is invoked for a severity 3 
error and the threshold associated with the error is reached, the 
following message is displayed: 


INDSYO03 Component information - xxxxxxxx Press any key 
to continue. 


“xxxxxxxx” contains the 2-byte return code for the information, followed by 
2 bytes of data. The 2 bytes of data can be unique for the system extension. 


Requesting Informational Messages with the System Extension Message 
Service 


Your system extension can use the System Extension Message service to 
issue its own informational message. The length of the message string must 
be 160 characters, and the message must be coded in host/notepad character 
format. See Appendix F, “Presentation Space Considerations,” for more 
information on host/notepad character formats. You can request the 
Translate Data service to translate an ASCII message to host/notepad 
character format before invoking the System Extension Message service. 
See Chapter 11, “Coding Translate Service Requests,” for a description of 
the Translate Data service. 
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When the System Extension Message service is requested to display a 
message string, the error handler displays the string and waits for a 
keystroke to be pressed by the user before continuing. The 3270 converged 
keyboard scan code of the key pressed is returned to the requester in the 


AL 


register. Be sure to include in your message a request to the user to 


press a certain key or any key to continue. 


Coding the System Extension Message Service to Identify Return Codes 


The format of the System Extension Message service to identify an error 
return code that will be used by your system extension as part of message 
INDSY001, INDSY002, or INDSY003 is shown below: 


Register Values Register Values 

on Request on Completion 

AX = X‘91’ CH = X‘72’ 

CH = Function ID of return code CL = Return code 

CL = Error number of return code 

DH = Threshold value The contents of registers 
DL = Severity value AX, BX, DX, ES, and DI 


Register Definitions 


are unpredictable. 


Request Registers: 
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The CH register contains the function ID of the return code. 
The CL register contains the error number of the return code. 


The DH register indicates the threshold value of the error, which is the 
number of times the error can occur before error message INDSY001, 
INDSY002, or INDSY003 is displayed. 


Note: Threshold values should start at 1 to have the message displayed. 
If the threshold is specified as 0, a message will never be issued 
when the error occurs. 


The DL register contains the severity value of the error. Possible 
severity values are: 


X‘01’ — A severity 1 error is an unrecoverable system error. The 
message that is displayed is INDSY001. The user can either press D to 
take a dump or press any other key to re-IPL the system. 


X‘02’ — A severity 2 error is a less serious error. The message that is 
displayed is INDSY002. The user can either press D to take a dump or 
press any other key to continue. 


Coding to Identify Return Codes 


X‘03’ — A severity 3 error is a minor error. The message that is 
displayed is INDSY003. The system continues running after the user 
presses another key. 


Requesting the System Extension Message Service 


To request the System Extension Message service, use the INT 7AH 
instruction to signal the workstation program that it has a request to 
process. 


Return Codes 


The CH and CL registers contain a return code generated by the error 
handler portion of the workstation program. Error handler return codes 
use a function ID of X‘72’ (found in the CH register). The error handler 
return codes that can be received for this service are: 


Code Meaning 


X‘00’ Successful completion of the request. 
X‘02’ The error table is full. 
X‘03’ Invalid severity specified. 


Usage Notes 


e Your system extension needs to identify the return codes that it will 
issue as part of message INDSY001, INDSY002, or INDSY003 only once. 
Typically, all return code identification can be done in the initialization 
portion of the system extension code. 


e Each return code must be identified one at a time. You cannot use a 
list to identify return codes. 


Coding Example 


INITIALIZE REGISTERS FOR SYSTEM EXTENSION MESSAGE SERVICE TO IDENTIFY 
A RETURN CODE THAT WILL BE ISSUED ALONG WITH MESSAGE INDSYOOIL1, 
INDSYO02, OR INDSYOO3. 


St eT a ST 


MOV AH,91H 
MOV CH,12H 
MOV CL,O2H 
MOV DL,O1H 
MOV DH,O1H 
MOV ES,DI 


FUNCTION ID IS X'12' 
ERROR NUMBER IS X'02' 
SEVERITY IS X'Ol' 
THRESHOLD IS X'Ol1' 


~e Se Ne te 


; SIGNAL WORKSTATION PROGRAM FOR SYSTEM EXTENSION MESSAGE SERVICE 


INT 7AH 
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Coding the System Extension Message Service to Request Error Messages 


Register Definitions 
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The format of the System Extension Message service to request error 
message INDSY001, INDSY002, or INDSY003 is shown below: 


Register Values Register Values 

on Request on Completion 

AH = X‘91’ AL = Scan code 

AL = X‘00’ or X‘80’ CH = X‘72’ 

BX = Two bytes of data or zero CL = Return code 

CH = Function ID of return code 

CL = Error number of return code The contents of registers 
DX = X‘00’ AH, BX, DX, ES, and DI 
DI = SP register value are unpredictable. 


Request Registers: 


The AH register indicates whether you have pushed registers on the 
stack to be included in the dump data if a dump is taken. 


~- X‘00’ indicates that the registers are not to be displayed if a dump is 
taken. 

— X‘80’ indicates that the registers are to be displayed if a dump is 
taken. 


The BX register must contain 2 bytes of data that are to be included in 
message INDSY001, INDSY002, or INDSY003, or may contain all zeros. 
These 2 bytes of data can be used as an extended return code. 

The CH register contains the function ID of the return code. 


The CL register contains the error number of the return code. 


The DI register must contain the value of the SP register before issuing 
INT 7AH. 


Completion Registers: 


The AL register contains the scan code for the key pressed by the user 
in response to message INDSY001, INDSY002, or INDSY008. The error 
handler first intercepts this key to determine whether some action must 
be taken. If the keystroke causes a dump to be taken or the system to 
re-IPL, that action will be taken by the system. All other keys are 
passed to your system extension. See Appendix A, 
“Scan-Code/Shift-State and ASCII/ASCII-Mnemonic Values,” for scan 
code values. 


Coding to Request Error Messages 


Requesting the System Extension Message Service 


Return Codes 


Usage Notes 


Coding Example 


. 
I 


To request the System Extension Message service, use the INT 7AH 
instruction to signal the workstation program that it has a request to 
process. 


The CH and CL registers contain a return code generated by the error. 
handler portion of the workstation program. Error handler return codes 
use a function ID of X‘72’ (found in the CH register). The error handler 
return codes that can be received for this service are: 


Code Meaning 


X ‘00’ Successful completion of the request. 
X‘01’ Return code was not previously identified. 


e The System Extension Message service request will not be completed 
successfully unless the return code associated with the error has been 
previously identified to the error handler. 


EXTENDED RETURN CODE DECLARATION 


EXT DW 


. 
f 
° 
, 


. 
f 


1306H 


PUSH ALL REGISTERS FOR DUMP 


PUSH 
PUSH 
PUSH 
PUSH 
PUSH 
PUSH 
PUSH 
PUSH 
PUSH 
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me “ee Me Ne 


’ 


INITIALIZE REGISTERS FOR SYSTEM EXTENSION MESSAGE SERVICE TO REQUEST 


ERROR MESSAGE INDSYOO1, 


MOV 
MOV 


MOV 
MOV 
MOV 


MOV 
MOV 


AH,91H 
AL, 80H 


BX, EXT 
CH,12H 
CL,O2H 


DX ,OOH 
DI,SP 


INDSY002, 


bl a al i BL i i a el Bil al | 


OR INDSYO0O3. 


REGISTERS HAVE BEEN SAVED 

ON THE STACK FOR DUMP 

TWO BYTES OF DATA TO FOLLOW 
THE MESSAGE 

FUNCTION ID IS X'12' 

ERROR NUMBER IS X'02' 

NOTE THAT THIS ERROR CODE WAS 
IDENTIFIED IN THE PREVIOUS EXAMPLE 
MUST BE X'OO' 

POINT TO REGISTERS SAVED ON 
THE STACK 


SIGNAL WORKSTATION PROGRAM FOR SYSTEM EXTENSION MESSAGE SERVICE 


INT 


POP ALL SAVED REGISTERS 


POP 
POP 
POP 
POP 
POP 
POP 
POP 
POP 
POP 


7AH 


Coding to Request Informational Messages 


Coding the System Extension Message Service to Request Informational 


Messages 


Register Definitions 


The format of the System Extension Message service to request 
informational messages is shown below: 


Register Values Register Values 

on Request on Completion 

AH = X‘91’ AL = Scan code 

AL = X‘00’ CH = X‘72’ 

CX = X‘7FFF’ CL = Return code 

ES = Segment address of the message string 

DI = SP register value The contents of registers 
DX = Offset address of the message string AL, BX, DX, ES, and DI 


are unpredictable. 


Request Registers: 


The ES and DX registers contain the segment and offset addresses of 
the message string to be displayed. The length of the message string 
must be 160 characters, and the message must coded in host/notepad 
character format. You can request the Translate Data service to 
translate an ASCII message to host/notepad character format before 
requesting the System Extension Message service. Refer to 

Chapter 11, “Coding Translate Service Requests,” for the host 
characters. It is suggested that the first character of the message be a 
blank. 


The DI register must contain the value of the SP register before issuing 
INT 7AH. 


Completion Registers: 


The AL register contains the scan code of the key that was pressed by 
the user in response to the message. Scan code values are found in 
Appendix A, “Scan-Code/Shift-State and ASCII/ASCI-Mnemonic 
Values.” 


Note: When the System Extension Message service is requested to 
display a message string, the error handler displays the string and 
waits for a keystroke to be pressed by the user before continuing. 
This keystroke is passed directly to your system extension. Be sure 
to include in your message a request to the user to press a certain 
key or any key to continue. 
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Requesting the System Extension Message Service 


Return Codes 


Usage Notes 


Coding Example 


24-24 


To request the System Extension Message service, use the INT 7AH 
instruction to signal the workstation program that it has a request to 
process. 


The CH and CL registers contain a return code generated by the error 
handler portion of the workstation program. Error handler return codes 
use a function ID of X‘72’ (found in the CH register). The error handler 
return code that can be received for this service is: 


Code Meaning 


X‘00’ Successful completion of the request. 


e The message displayed by this service is treated as a severity 3 message. 


After the message is displayed, the error handler waits for a keystroke 
from the user and then returns control to your system extension. 
Because of this, you should include in your message a prompt asking 
the user to press a key. 


e The message string must be 160 characters long. It is suggested that 
the first character of each message be a blank. 


e If any return codes are issued as part of this message, they do not have 


to be identified with the error handler. 


; THE USER-DEFINED MESSAGE 


MSG 


~e Me Me Ne 


10H,B3H,87H,88H,92H,10H,88H,92H,10H,80H,8DH,10H 
84H,97H,80H, 8CH, 8FH, 8BH, 84H, 10H, 8EH, 85H, 10H, 80H, 8DH, 10H 
A8H,8DH,93H,84H,91H,8DH, 80H, 8BH,10H,A2H, 8EH, 83H, 84H 
8FH,8EH,88H,8DH,93H,10H,8CH, 84H, 92H, 92H, 80H, 86H, 84H, 32H 


THE ABOVE MESSAGE SAYS: THIS IS AN EXAMPLE OF A CODEPOINT MESSAGE 


aA DUP (10H) 


; 
; PAD WITH BLANKS TO EQUAL 80 CHARACTERS 


10H, AFH, 91H,84H,92H,92H,10H,80H, 8DH, 98H, 10H, 8AH, 84H, 98H 
10H, 93H, 8EH,10H,82H,8EH,8DH, 93H, 88H, 8DH, 94H, 84H, 32H 


; THE ABOVE MESSAGE SAYS: PRESS ANY KEY TO CONTINUE 


ae) DUP (10H) 


e 
‘ 


. 
! 


Coding to Request Informational Messages 


PAD WITH BLANKS TO EQUAL 80 CHARACTERS 


i 
;SAVE ALL REGISTERS 


e 
’ 


PUSH 
PUSH 
PUSH 
PUSH 
PUSH 
PUSH 
PUSH 
PUSH 
PUSH 


AX 
BX 
CX 
DX 
BP 
SI 
DI 
DS 
ES 


INITIALIZE REGISTERS FOR SYSTEM EXTENSION MESSAGE SERVICE TO REQUEST 


AN INFORMATI 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


ONAL MESSAGE. 


AH,91H 

AL ,OOH 

CX, 7FFFH 
DX,OFFSET MSG 
ES,SEGMENT MSG 
DI,SP 


MUST BE X'OO'. 

MUST BE X'7FFF' 

DX OFFSET ADDRESS OF THE MESSAGE 
ES SEGMENT ADDRESS OF THE MESSAGE 


SIGNAL WORKSTATION PROGRAM FOR SYSTEM EXTENSION MESSAGE SERVICE 


INT 


RESTORE ALL 


POP 
POP 
POP 
POP 
POP 
POP 
POP 
POP 
POP 


7AH 


REGISTERS 


ES 
DS 
DI 
SI 
BP 
DX 
CX 
BX 
AX 
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Managing Resources 


If your system extension is going to manage internal resources (for 
example, control blocks or hardware) for applications in stoppable 
environments, it must include a resource manager. A resource manager is 
a component that is called by the environment manager when a stoppable 
environment to which the system extension has allocated resources is being 
stopped. This allows the system extension to reclaim resources outstanding 
in that stoppable environment. In order for your system extension’s 
cleanup component to be notified when a PC environment is stopped (so 
your system extension can reclaim resources used for that PC environment), 
it must have added a resource to the PC environment’s chain. 


When a PC environment is stopped, the environment manager notifies all 
the resource manager’s cleanup components that have a resource on the PC 
environment chain that the environment is being stopped. Thus, it is 
important for your system extension to add a resource to any PC 
environment about which it is to be notified. If your system extension that 
handles requests from a PC is a component, then it is running under the 
PC task that is in the PC environment, and it can simply add a resource to 
the current active task environment. 


If the system extension that handles requests from a PC is a task, then it is 
executing in a different environment from the PC. When it received the 
request, the DX register contained the task ID of the task that made the 
request. Your system extension must add a resource to the environment of 
the task (in the DX register) that made the request. 


If a resource is added to the PC environment, the resource managers that 
added the resource are notified (via the cleanup component) when the PC 
environment is stopped. Resource managers are described in 
Chapter 22, “Environments and the Environment Manager.” 


Design Considerations for System Extensions and the 


XMA Card 
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When the XMA card is used and there are multiple PC sessions, each PC 
session is in its own 1-megabyte address space. This was not the case in 
Release 2.1, where all PC sessions shared the same 1-megabyte address 
space; thus PC sessions and system extensions could pass information in 
any way, and avoiding the Application Program Interface (API) would not 
cause a problem. With the XMA card, PC sessions cannot communicate 
directly with one another, since the storage of one PC session is not 
addressable from the second. System extensions are loaded in the 
1-megabyte address space of all PC sessions, so all the PC sessions can 
communicate with a system extension. 


Components 


Tasks 


Design Considerations 


In a Release 4.0 system, all tasks are assigned an address space to run in. 
Each task can address 1 megabyte of storage. Since each PC is in its own 
address space, a single task cannot address storage in all the PC sessions at 
the same time. To interface a system extension to all PC sessions, the 
following elements of the API should be used. 


Components installed by a system extension always run on the PC sessions 
task in the PC sessions address space. There is no problem passing 
information to and from all PC sessions using components. 


Tasks installed by a system extension initially run in the address space of 
the workstation program, since during initialization of the system extension 
there are no PC sessions created yet. The workstation program has built 
into the Get a Request service on the API an automatic switching of 
address spaces. When a task does a Get a Request service, the task is 
switched to the address space of the requesting PC session. The task 
continues to run in this address space until another Get a Request call is 
done. The Get a Request call is the only one that causes the address space 
to change; waiting for a signal, timer, semaphore, fixed-length queue, or a 
completion queue request (RQE) does not change the address space. 


Fixed-Length Queues 


General Notes 


When a fixed-length queue is created, it is assigned to an address space. 
The workstation program is aware of which address space the queue is in, 
and Enqueue Data and Dequeue Data services can be used to pass data 
between address spaces. Note that the data is passed, but if pointers to data 
are passed in the queue, the pointer may not be valid in the address space 
of the task that did the dequeue. 


System extensions that rely on absolute addresses may have problems 
handling requests from multiple PC sessions. Since the PC sessions are in 
different address spaces, the PC sessions are located at the same address 
within the 1-megabyte address. If you run the same program in three 
different PC sessions, and that program passes an address to the system 
extension, the address could be exactly the same for all three PC sessions. 
If your system extension needs to track which PC made the request, the 
Query Task’s Environment ID call can be used to distinguish between the 
different PC sessions. Each PC has a unique environment ID. 
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Part 4. Sample Programs 


This part contains five sample programs that use the services of the API. 


e Sample Program 1 (Chapter 25) locks all keyboard input until the 
correct password is typed. 


e Sample Program 2 (Chapter 26) prevents a 3270 PC user from using the 
Work Station Control windowing features, allowing a user to set up the 
screens using the RESTORE utility but not to change the setup of the 
windows on the screen. 


e Sample Program 3 (Chapter 27) presents a summary of the currently 
active sessions. 


e Sample Program 4 (Chapter 28) accesses data from the host and displays 
the information about a business in a personal computer window in bar 
chart form. 


e Sample Program 5 (Chapter 29) is the second half of Sample Program 4. 
It should be linked with Sample Program 4 at link-edit time. 


Part 4. Sample Programs 


Sample Program 1 


Chapter 25. Sample Program 1 


TITLE LOCKKYBD 
PAGE 80,132 


PROGRAM : LOCKKYBD 
FUNCTION : 

THIS PROGRAM LOCKS ALL KEYBOARD INPUT UNTIL THE CORRECT PASSWORD 
IS TYPED. THIS PREVENTS UNWANTED USERS FROM GAINING ACCESS TO 3270 
PC FUNCTIONS AND DATA. THE USER INVOKING THE PROGRAM IS PROMPTED 
TO ENTER A PASSWORD. THIS PASSWORD MUST BE REENTERED IN ORDER TO 
REGAIN ACCESS TO THE 3270 PC. 

TO DO THIS, TWO OTHER TASKS ARE CREATED. THE FIRST TASK IN- 
TERCEPTS THE WSCTRL KEYSTROKES TO KEEP THE USER FROM ACCESSING 
WSCTRL FUNCTIONS. THIS IS ACCOMPLISHED BY CONNECTING TO THE WSCTRL 


KEYBOARD, INTERCEPTING THE KEYSTROKES AND IGNORING THEM. 

THE SECOND TASK PREVENTS THE PC IPL SEQUENCE (CTRL-ALT-DEL) FROM 
REACHING THE PC SESSION, THUS PREVENTING THE USER FROM RESTARTING THE 
SYSTEM TO GAIN ACCESS TO ANY FUNCTIONS OR DATA. THIS SECOND TASK IS 
CONNECTED TO THE PC SESSION'S KEYBOARD. IT INTERCEPTS THE KEYSTROKES 
GOING TO THE PC AND CHECKS FOR THE CTRL-ALT-DEL SEQUENCE. THIS KEY- 
STROKE IS IGNORED, WHILE ALL OTHERS ARE PASSED ON TO THE PC SESSION. 

A SIGNAL MUST BE SENT TO THE TASKS TO TELL THEM WHEN TO STOP 
READING KEYSTROKES. THE READ KEYSTROKE FUNCTION PUTS A REQUEST QUEUE 
ELEMENT (ROE) ON THE KEYSTROKING QUEUE TO SIGNAL THAT IT IS WAITING 
FOR DATA IN THE QUEUE. SINCE THE TASKS ARE ALWAYS LOOPING BACK TO 
GET KEYSTROKES, THERE ARE ALWAYS RQE'S ON THE KEYSTROKING QUEUES. 
THIS CAUSES A PROBLEM DURING CLEAN UP SINCE THE WORKSTATION PROGRAM WILL 
NOT ALLOW A FIXED-LENGTH QUEUE WITH AN RQE ON IT TO BE DELETED. so 
AN UNUSED SCAN CODE IS SENT TO THE TASKS TO SIGNAL THAT IT IS TIME TO 
STOP READING KEYSTROKES, THUS KEEPING RQE'S OFF THE KEYSTROKING 
QUEUES. 


THIS PROGRAM USES THE FOLLOWING API FUNCTIONS: 


CONNECT TO KEYBOARD 
CREATE A FIXED LENGTH QUEUE ENTRY 
CREATE A TASK ENTRY 
DELETE AN ENTRY 
DISCONNECT FROM KEYBOARD 
RETURN TO DISPATCHER 
ENQUEUE DATA 

NAME RESOLUTION 

QUERY SESSION ID 

QUERY BASE WINDOW 

QUERY ACTIVE TASK 

READ KEYSTROKE 

SET A TASK "READY" 

SET A TASK "“UNREADY" 
WRITE KEYSTROKE 


ST et et ee eT ee eT YT eT TT TT TT TT tT a a a tT a | i i i, eT eT eT a eT | ee nT eT ee TY 


SUBTTL MACROS 
PAGE 


Pree eprrevorv are erere eee 
3; SET UP MACROS ;; 


eoeevr eee eee eee ee eee ee 


rPrerreyrerrervrererereaearaeae se 
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MACRO : DOSFUNCT 

FUNCTION : 
ISSUE THE DOS CALL WITH THE FUNCTION NUMBER PASSED IN 
FUNCTNUM. 


eT ee et eT ee TY 


DOSFUNCT MACRO FUNCTNUM 


MOV AH , FUNCTNUM 
INT 21H 


ENDM 


MACRO : PROMPT 
FUNCTION 
DISPLAY THE PROMPT "ENTER PASSWORD : " 


et et eT eT 


; ESTABLISH CONSTANTS 


DISPSTR EQU 9 ; DOS DISPLAY STRING FUNCTION NUMBER 
PROMPT MACRO 
LEA DX,PASSPRMT ; POINT DX TO THE START OF THE PROMPT 
DOSFUNCT DISPSTR ; DISPLAY THE PROMPT STRING 
ENDM 


MACRO : DISPLAY 
FUNCTION 
DISPLAY THE CHARACTER PASSED IN CHAR. 


ST ek ee 


; ESTABLISH CONSTANTS 
DISPCHAR EQU 2 ; DOS DISPLAY CHARACTER FUNCTION NUMBER 


DISPLAY MACRO CHAR 


MOV DL, CHAR ; PUT THE CHARACTER IN DL 
DOSFUNCT DISPCHAR ; DISPLAY THE CHARACTER 
ENDM 


MACRO : CHEK4ERR 
FUNCTION : 
SET UP THE REGISTERS FOR THE ERROR CHECKER PROCEDURE. 


se Ne Ne Ne ONO 


29-2 


CHEK4ERR 


~e NO Ne NO Ne 


MACRO RETNCODE 


IFNB <RETNCODE> 
MOV _BL,RETNCODE 
ELSE 

MOV _BL,O 

ENDIF 


“eo Ne NO ote 


CALL CHECKERR 


“oe 


ENDM 


MACRO NAME : CONNSKEY 

PARAMETERS : SERVTYPE 
SESSID 
KEYSTOQ 


_. KEYSTROKE QUEUE ID 


EVNTQ 


EVENT QUEUE ID 


e 
, 
e 
t 
° 
f 


CONNSKEY 


FUNCTION 


Sample Program 1 


IF THERE IS A PARAMETER LIST RETURN CODE 
SPECIFIED, PASS IT TO THE ERROR CHECKER 
iN. Biss 

OTHERWISE, SEND A O IN BL 


CALL THE ERROR CHECKER 


-- RESOLVED VALUE FOR 'KEYBOARD' 
-- SESSION ID 


CONNECT THE KEYBOARD TO THE SPECIFIED SESSION. 


MACRO SERVTYPE,SESSID,KEYSTQ,EVNTO 


; INITIALIZE PARAMETER LIST FOR CONNSKEY 


MOV CKRETNCD ,OOH 
MOV CKFXNID,O0OH 
MOV AL,SESSID 
MOV CKSESSID,AL 


IFNB <KEYSTQ> 
MOV AX,KEYSTQ 
ELSE 

MOV AX, 0 

ENDIF 

MOV  CKKEYSTQ,AX 


IFNB <EVNTQ> 
MOV AX,EVNTQ 
ELSE 

MOV AX,0 

ENDIF 

MOV CKEVENTQ,AX 


; INITIALIZE REGISTERS 
MOV AH,O9H 

MOV AL,O1H 

MOV BH,80H 

MOV BL,20H 

MOV CX,0O0O00H 

MOV DX,SERVTYPE 

MOV DI, SEG CKRETNCD 
MOV ES,DI 

MOV DI,OFFSET CKRETN 


~e Ne Ne 


=e 


=e 


~e 


FOR 


° 
f 
e 
i 
f 
f 


CD 


RETURN CODE MUST = O BEFORE REQUEST 
FUNCTION ID MUST = 0 BEFORE REQUEST 
SESSION ID INTO THE LIST 


IF A KEYSTROKE QUEUE WAS SPECIFIED, 
PUT IT INTO THE LIST 


IF AN EVENT QUEUE WAS SPECIFIED, 
PUT IT INTO THE LIST 


CONNSKEY 


RESOLVED VALUE FOR 'KEYBOARD' 

SEGMENT ADDRESS OF PARAMETER LIST 
IN ES 

OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR CONNSKEY SERVICE 


INT 7AH 


ENDM 
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~e “Me Ne Se Ne NO Me Ne 


CRTSQ 


Ce et eT et ee eT eT eT eT TY 


CRTSTASK 
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MACRO NAME : CRTSQ 


PARAMETERS : QSEGMENT -- SEGMENT OF QUEUE 
QOFFSET -- OFFSET OF QUEUE 
QSIZE -- SIZE OF QUEUE 
FUNCTION 


CREATE A FIXED LENGTH QUEUE. 


MACRO QSEGMENT,QOFFSET,QSIZE 


; INITIALIZE PARAMETER LIST FOR CRTSQ 


MOV AX,QSEGMENT ; SEGMENT ADDRESS INTO THE LIST 
MOV  CQSEGMEN,AX 
MOV AX,QOFFSET ; OFFSET INTO THE LIST 


MOV  CQOFFSET,AX 


; INITIALIZE REGISTERS FOR CRTSQ 

MOV AH,O4H ; 

MOV BL,OOH ; NO NAME SPECIFIED 

MOV CX,QSIZE ; SIZE OF THE QUEUE 

MOV DxX,0000H ; DX MUST = O FOR THE REQUEST 


MOV DI, SEG CQOFFSET SEGMENT ADDRESS OF PARAMETER LIST 
MOV ES,DI IN ES 


MOV DI,OFFSET CQOFFSET OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR CRTSQ SERVICE 
INT 7AH 


ENDM 


MACRO NAME : CRTSTASK 


PARAMETERS : TASK -- TASK TO BE CREATED 

NAME -- NAME OF THE TASK 

STACK -- STACK FOR THE TASK 

PREEMPT -- PREEMPTION TYPE 

PRIORITY -- PRIORITY OF THE TASK 

DATA -- VARIABLE IN THE TASK'S DATA SEGMENT 
FUNCTION 


CREATE A TASK. 


MACRO TASK,NAME,STACK,PREEMPT,PRIORITY ,DATA 


; INITIALIZE PARAMETER LIST FOR CRTISTASK 

MOV AX,OFFSET STACK ; GET THE OFFSET OF THE TASK'S STACK 
ADD AX, 232 ; INCREMENT THE SP TO POINT AT THE 

: START OF REGISTER RESTORE AREA 

; PUT TASK'S SP IN PARAMETER LIST 

; PUT TASK'S SS IN PARAMETER LIST 


MOV CTTASKSS , AX 
MOV AX,SEG STACK 
MOV CTTASKSP , AX 


MOV BL,O ; BL = O IF NO NAME SPECIFIED 


REP 


Oe et eT eT TY 


DELSENT 


Sample Program 1 


IF THERE IS A NAME SPECIFIED, PUT 
IT IN THE PARAMETER LIST 

BL = 1 IF A NAME IS SPECIFIED 

ES:DI POINT TO DESTINATION IN 
PARAMETER LIST 


IFNB <NAME> 


MOV BL,1 

MOV AX,SEG CTTSKNAM 
MOV ES,AX 

MOV DI,OFFSET CTTSKNAM 
MOV SI,OFFSET NAME 


se eo te Se Ne 


DS:SI POINT TO SOURCE OF THE NAME 


MOV CX,8 ; MOVE 8 BYTES 

MOVSB ; COPY THE NAME INTO THE PARM LIST 
ENDIF 

; INITIALIZE THE TASK'S STACK 

PUSH DS ; SAVE DS 

MOV AX,SEG STACK ; GET THE TASK'S STACK SEGMENT 

MOV DS,AX 

MOV SI,OFFSET STACK ; DS:SI NOW POINT TO THE TASK STACK 
MOV WORD PTR [SI+254],0F242H ; SET FLAGS IN THE STACK 

MOV AX,SEG TASK 

MOV WORD PTR [SI+252],AX ; SET SEGMENT OF TASK IN STACK 
MOV AX,OFFSET TASK 

MOV WORD PTR [SI+250],AX ; SET OFFSET OF TASK IN STACK 


IFNB <DATA> 
MOV AX,SEG DATA 


MOV WORD PTR [S1I+234],AX ; SET DATA SEGMENT IN STACK 
ENDIF 
POP DS ; RESTORE DS 


; INITIALIZE REGISTERS FOR CRTSTASK 

MOV AH,92H : 

MOV BH,PREEMPT ; PREEMPTION TYPE IN BH 

MOV CX,PRIORITY ; PRIORITY IN CX 

MOV DI, SEG CTTASKSS  ; SEGMENT ADDRESS OF PARAMETER LIST 
MOV ES,DI ; INES 

MOV DI,OFFSET CTTASKSS ; OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR CRTSTASK SERVICE 
INT 7AH 


ENDM 


MACRO NAME : DELSENT 
PARAMETERS : ENTRYID -- ID OF THE ENTRY TO BE DELETED 
FUNCTION 

DELETE AN ENTRY FORM THE SYSTEM. 


MACRO ENTRYID 
; INITIALIZE REGISTERS FOR DELSENT 
MOV AH,O6H 
MOV CX,0000H 
MOV DX,ENTRYID ; DX = ENTRY ID 


;SIGNAL WORKSTATION PROGRAM FOR DELSENT SERVICE 
INT 7AH 


ENDM 


Chapter 25. Sample Program 1 


25-5 


Sample Program 1 


bt et eT et eT 


DISCSKEY 


=e we we Ne Ne Ne 


DISPSRET 
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MACRO NAME : DISCSKEY 
PARAMETERS : SERVTYPE -- RESOLVED VALUE FOR 'KEYBOARD' 
SESSID ~- SESSION ID 
FUNCTION : 
DISCONNECT THE KEY BOARD FROM THE SPECIFIED SESSION. 


MACRO SERVTYPE,SESSID,TASKID 


; INITIALIZE PARAMETER LIST FOR DISCSKEY 


MOV DKRETNCD , OOH ; RETURN CODE MUST = 0 BEFORE REQUEST 
MOV DKFXNID , OOH ; FUNCTION ID MUST = 0 BEFORE REQUEST 
MOV AL,SESSID ; SESSION ID INTO THE LIST 


MOV DKSESSID,AL 


IFNB <TASKID> 


MOV AX ,TASKID ; IF A TASK ID WAS SPECIFIED, PUT IT 
ELSE ; IN THE LIST 

MOV AX ,O000H 

ENDIF 


MOV DKTASKID , AX 


; INITIALIZE REGISTERS FOR DISCSKEY 

MOV AH,O9H 

MOV AL,O2H 

MOV BH,80H 

MOV BL,20H 

MOV CX,OO00H 

MOV DX,SERVTYPE ; RESOLVED VALUE FOR 'KEYBOARD' 

MOV DI, SEG DKRETNCD ; SEGMENT ADDRESS OF PARAMETER LIST 
MOV ES,DI ; IN ES 

MOV DI,OFFSET DKRETNCD ; OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR DISCSKEY SERVICE 
INT 7AH 


ENDM 


MACRO NAME : DISPSRET 
PARAMETERS : WAITTYPE -- WAIT TYPE 
FUNCTION 

RETURN TO THE DISPATCHER. 


MACRO WAITTYPE 

; INITIALIZE REGISTERS FOR DISPSRET 

MOV AH, 95H 

MOV BL,WAITTYPE ; WAIT TYPE IN BL 


; SIGNAL WORKSTATION PROGRAM FOR DISPSRET SERVICE 
INT 7AH 


ENDM 


et ee et et eT eT eT 


Sample Program 1 


MACRO NAME : ENQUEUE 


PARAMETERS : NUMBYTES -- NUMBER OF BYTES TO BE ENQUEUED 
QUEUEID -- FIXED LENGTH QUEUE ID 
DATANAME -- MEMORY LOCATION NAME OF THE DATA 
FUNCTION 


USE THIS SERVICE TO ENQUEUE DATA ON THE SPECIFIED FIXED 
LENGTH QUEUE ID. 


ENQUEUE MACRO NUMBYTES, QUEUEID, DATANAME 


; INITIALIZE REGISTERS FOR ENQUEUE 


MOV AH,OCH ; 

MOV  CX,NUMBYTES ; NUMBER OF BYTES 

MOV DX,QUEUEID ; QUEUE ID 

MOV DI, SEG DATANAME  ; SEGMENT ADDRESS OF DATA 

MOV ES,DI ; IN ES 

MOV DI,OFFSET DATANAME ; OFFSET OF DATA IN DI 

; SIGNAL WORKSTATION PROGRAM FOR ENQUEUE SERVICE 

INT  7AH 

ENDM 
; PARAMETERS : NRSSERVN -- LOCATION OF THE 8-BYTE 
; SERVICE NAME. I.E.'SESSMGR ' 
; NRS$SERVT -- RETURN CODE FROM PARAMETER LIST 
NAMESRES MACRO NRSSERVN , NRSSERVT 


; SET UP 
MOV 
MOV 
MOV 
MOV 
MOV 


; SIGNAL 
INT 


; RETURN 
MOV 


ENDM 


REGISTERS NAMESRES 


AX,SEG NRSSERVN SEGMENT ADDRESS OF PARM LIST 


ES ,AX ; ES = SEGM ADDRESS OF PARM LIST 
AH, 81H ; AH = X'81* 

CX ,0000H ; CX = xX'0000' 

DI,OFFSET NRSSERVN ; DI = OFFSET ADDR. OF PARM LIST 


WORKSTATION PROGRAM FOR NAMESRES SERVICE 
7AH 


SERVICE TYPE ID TO CALLER 
NRSSERVT, DX 


MACRO NAME : QUERYSID 


, 

4 

; PARAMETERS : SERVTYPE -- RESOLVED VALUE FOR 'SESSMGR ' 
? NAMEARRY ~-- NAME ARRAY 

: OPTION -- OPTION BYTE 

; DATA -~- DATA BYTE 

; LONGNAME -- SESSION LONG NAME 
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QUERYSID 


REP 
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FUNCTION 
GET THE SESSION ID(S) OF THE SESSION(S) SPECIFIED BY 
THE OPTION AND DSTS BYTES AND RETURNS THEM IN THE NAME 
ARRAY. 
NOTE - THE NAME ARRAY IS SET UP BY THE USER AND MUST HAVE 
THE LENGTH OF THE ARRAY CONTAINED IN THE 1ST BYTE. 


MACRO SERVTYPE,NAMEARRY , OPTION, DATA, LONGNAME 


; INITIALIZE PARAMETER LIST FOR QUERYSID 

MOV  QDRETNCD,OOH RETURN CODE MUST = O BEFORE REQUEST 
MOV QDFXNID,OOH FUNCTION ID MUST = O BEFORE REQUEST 
MOV  AL,OPTION OPTION BYTE INTO THE LIST 

MOV QDOPTION,AL 

MOV AL,DATA ; DATA BYTE INTO THE LIST 

MOV QDDATA,AL 

MOV AX,OFFSET NAMEARRY ; NAME ARRAY OFFSET INTO THE LIST 
MOV QDNAMOFF,AX 

MOV AX,SEG NAMEARRY ; NAME ARRAY SEGMENT INTO THE LIST 
MOV  QDNAMSEG,AX 


we Ne Ne 


IFNB <LONGNAME> ; CHECK IF A LONG NAME WAS SPECIFIED 


CLD ; COPY DIRECTION = FORWARD 
MOV AX,SEG QDLNGNAM 
MOV ES ,AX 

MOV DI,OFFSET QDLNGNAM 
MOV SI,OFFSET LONGNAME 


ES:DI POINTS TO DESTINATION IN PARM 
LIst 
DS:SI POINTS TO SOURCE OF LONG NAME 


we Ne Me Ne NO 


MOV CxX,8 MOVE 8 BYTES 
MOVSB COPY LONG NAME INTO THE PARM LIST 
ENDIF 


; INITIALIZE REGISTERS FOR QUERYSID 

MOV AH ,O9H 

MOV AL,O1H 

MOV BH, 80H 

MOV BL,20H 

MOV CX ,OO000H 

MOV DX,SERVTYPE ; RESOLVED VALUE FOR 'SESSMGR ' 

MOV DI, SEG QDRETNCD ; SEGMENT ADDRESS OF PARAMETER LIST 
MOV ES,DI ; IN ES 

MOV DI,OFFSET QDRETNCD ; OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR QUERYSID SERVICE 
INT 7AH 


ENDM 


MACRO NAME : QSBASSW 
PARAMETERS : SERVTYPE -- RESOLVED VALUE FOR 'SESSMGR ' 
FUNCTION : 

FIND THE SESSION ID AND SHORT NAME FOR THE BASE WINDOW 
OF AN ENVIRONMENT. 


QOSBASSW 


me Ne Ne te Ne 


OSTASK 


St ee ee eT eT eT 


READSKEY 
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MACRO SERVTYPE 


; INITIALIZE PARAMETER LIST FOR QSBASSW 
MOV QSRETNCD, 00H ; RETURN CODE MUST 
MOV QOSFXNID,OOH ; FUNCTION ID MUST 


; INITIALIZE REGISTERS FOR QSBASSW 
MOV AH,09H 
MOV AL,OAH 
MOV BH,80H 
MOV BL,20H 
MOV CX,OFFH 
MOV DX,SERVTYPE 
MOV ES,DI IN ES 
MOV DI,OFFSET QSRETNCD 


; SIGNAL WORKSTATION PROGRAM FOR QS$BASSW SERVICE 
INT 7AH 


ENDM 


MACRO NAME : QSTASK 
FUNCTION : 
GET THE ID OF THE CURRENT ACTIVE TASK. 


MACRO 


; INITIALIZE REGISTERS FOR QSTASK 
MOV AH , 9CH 


; SIGNAL WORKSTATION PROGRAM FOR QSTASK SERVICE 
INT 7AH 


ENDM 


MACRO NAME : READSKEY 
PARAMETERS : SERVTYPE -- SERVICE TYPE 
SESSID -~- SESSION ID 
FUNCTION 
READ KEYSTROKE DATA. 


MACRO SERVTYPE,SESSID,TASKID 


; INITIALIZE PARAMETER LIST FOR READSKEY 


MOV RKRETNCD, OOH ; RETURN CODE MUST = 0 BEFORE REQUEST 
MOV RKFXNID,0OOH ; FUNCTION ID MUST = 0 BEFORE REQUEST 


MOV AL,SESSID 
MOV RKSESSID,AL 


IFNB <TASKID> 


MOV AX, TASKID ; IF A TASK ID WAS SPECIFIED PUT IT 
ELSE ; IN THE LIST, ELSE PUT IN A O 


MOV AX, 0 
ENDIF 
MOV RKTASKID,AX 
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; RESOLVED VALUE FOR 'SESSMGR 
MOV DI, SEG QSRETNCD ; SEGMENT ADDRESS OF PARAMETER LIST 


SESSION ID INTO THE LIST 


O BEFORE REQUEST 
O BEFORE REQUEST 


OFFSET OF PARAMETER LIST IN DI 
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Sample Program 1 


; INITIALIZE REGISTERS FOR READSKEY 

MOV  AH,09H 

MOV AL ,03H 

MOV BH, 80H 

MOV BL,20H 

MOV CX, OFFH 

MOV DX,SERVTYPE 7 SERVICE TYPE IN DX 

MOV DI, SEG RKRETNCD ; SEGMENT ADDRESS OF PARAMETER LIST 
MOV ES ,DI ; IN ES 

MOV DI,OFFSET RKRETNCD ; OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR READSKEY SERVICE 
INT 7AH 


ENDM 


MACRO NAME : SETSRDY 
PARAMETERS : TASKID -~- TASK ID 
WAITTYPE -- WAIT TYPE 
FUNCTION 
SET THE SPECIFIED TASK TO THE "READY" STATE. 


ue we te Ne Se Se Ne 


SETSRDY MACRO TASKID,WAITTYPE 


; INITIALIZE REGISTERS FOR SETSRDY 
MOV AH, 02H 


MOV BL,WAITTYPE ; WAIT TYPE IN BL 

MOV DX, TASKID ; TASK ID IN DX 

; SIGNAL WORKSTATION PROGRAM FOR SETSRDY SERVICE 
INT 7AH 

ENDM 


MACRO NAME : SETUNRDY 
PARAMETERS : TASKID -~- TASK ID 
WAITTYPE -~- WAIT TYPE 
FUNCTION : 
SET THE SPECIFIED TASK TO THE "UNREADY" STATE. 


et et et et eT 


SETUNRDY MACRO TASKID,WAITTYPE 


; INITIALIZE REGISTERS FOR SETUNRDY 
MOV AH ,05H 


MOV BL,WAITTYPE | ; WAIT TYPE IN BL 

MOV DX, TASKID ; TASK ID IN DX 

; SIGNAL WORKSTATION PROGRAM FOR SETUNRDY SERVICE 
INT 7AH 

ENDM 
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ot et eT eT | eT eT eT eT eT eT 


WRITSKEY 


MACRO 
PARAMETERS 


WRITSKEY 

SERVTYPE -- 
SESSID == 
SCANCD =< 
SHIFST == 
LLGTORr. = 
LISTSEG <-= 
TASKID == 


FUNCTION : 
SEND A KEYSTROKE OR A LIST OF KEYSTROKES TO THE 


SPECI 


MACRO 
LOCAL 


MOV 
MOV 
MOV 
MOV 


IFNB 


; SEN 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


ELSE 


FIED SESSION. 


Sample Program 1 


RESOLVED VALUE FOR 'KEYBOARD' 
SESSION ID 

SCAN CODE 

SHIFT STATE 

LIST OFFSET 

LIST SEGMENT 

CONNECTOR'S TASK ID 


SERVTYPE,SESSID,SCANCD,SHIFST,LISTOFF, LISTSEG, TASKID 


WKEND 


WKPARLST .WKRETNCD , OH 
WKPARLST.WKFXNID,OH 
AL,SESSID 

WKPARLST.WKSESSID,AL 


<SCNCD> 


DING ONE KEYSTROKE 


AL, SCANCD 
WKPARLST.WKSCNCOD , AL 
AL,SHIFST 

WKPARLST .WKSHFST, AL 
AL, 20H 
WKPARLST.WKOPTION, AL 


=e 


ose 


, 


WKRETCD MUST BE O FOR THE CALL 
WKFXNID MUST BE O FOR THE CALL 
PUT THE SESSION ID IN PARM LIST 


CHECK IF SENDING ONE KEYSTROKE 
OR A LIST OF KEYSTROKES 


PUT THE SCAN CODE IN THE PARM LIST 
PUT SHIFT STATE IN THE PARM LIST 


PUT THE OPTION BYTE FOR SENDING 
ONE CHARACTER IN THE PARM LIST 


; SENDING A LIST OF KEYSTROKES 


MOV 
MOV 
MOV 
MOV 


MOV 
MOV 


ENDIF 


IFNB 
MOV 
ELSE 
MOV 
ENDIF 
MOV 


AX ,LISTOFF 
WKPARLST.WKLSTOFF , AX 
AX, LISTSEG 
WKPARLST.WKLSTSEG, AX 


AL, 30H 
WKPARLST.WKOPTION, AL 


<TASKID> 
AX, TASKID 


AX ,0 


WKPARLST .WKTASKID ,AX 


PUT THE OFFSET ADDRESS OF THE LIST 
INTO THE PARAMETER LIST 

PUT THE SEGMENT ADDRESS OF THE 
LIST INTO THE PARAMETER LIST 


PUT OPTION BYTE FOR SENDING LIST 
OF CHARACTERS IN THE PARM LIST 


IF A CONNECTOR'S TASK ID WAS 
SPECIFIED, PUT IT IN THE LIST 


OTHERWISE PUT A O IN THE LIST 


; INITIALIZE THE REGISTERS FOR WRITSKEY 


MOV 
MOV 
MOV 
MOV 
MOV 


AH,O9H 
AL, 04H 
BH, 80H 
BL, 20H 
CX ,0000H 
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Sample Program 1 


MOV DX,SERVTYPE ; RESOLVED VALUE FOR 'KEYBOARD' 
MOV DI, SEG WKPARLST ; GET SEGMENT ADDRESS OF PARM LIST 
MOV ES,DI ; AND PUT IT IN ES 

MOV DI, OFFSET WKPARLST ; SET DI TO OFFSET OF PARM LIST 
INT 7AH ; PASS THE REQUEST TO THE API 

ENDM 

SUBTTL DATASEG 

PAGE 


DATASEG SEGMENT 'DATA' 


; PARAMETER LIST FOR CONNSKEY 


CKRETNCD DB 0 ; RETURN CODE 

CKFXNID DB 0O ; FUNCTION NUMBER 

CKSESSID DB 0 ; SESSION ID 

CKRESRV1 DB 0 ; RESERVED 

CKEVENTQ DW 0 ; EVENT QUEUE ID 

CKKEYSTO DW 0 ; KEYSTROKE QUEUE ID 
CKOPTION DB 40H ; OPTION BYTE (INTERCEPT ALL) 
CKRESRV2 DB 0 ; RESERVED 

; PARAMETER LIST FOR CRTSQ 

CQOFFSET DW O ; OFFSET OF THE QUEUE 
COSEGMEN DW 0 ; SEGMENT ADDRESS OF THE QUEUE 
CONAME DB 8 DUP(O) ; QUEUE NAME 

; PARAMETER LIST FOR CRTSTASK 

CTTASKSS DW 0 ; TASK'S STARTING SS 
CTTASKSP DW O ; TASK'S STARTING SP 
CTTSKNAM DB 8 DUP(?) ; TASK NAME 


; PARAMETER LIST FOR DISCSKEY 


DKRETNCD DB 0 ; RETURN CODE 

DKFXNID DB O ; FUNCTION NUMBER 
DKSESSID DB 0 ; SESSION ID 

DKRESRV1 DB 0 ; RESERVED 

DKTASKID DW 0 ; CONNECTOR'S TASK ID 
DKRESRV2 DB 0O ; RESERVED 


; PARAMETER LIST FOR QUERYSID 


QDRETNCD DB 
QDFXNID DB 
QDOPTION DB 


fe) RETURN CODE 
0 
0 
QDDATA DB 0 
0 
0 
8 


FUNCTION NUMBER 
OPTION BYTE 

DATA BYTE 

OFFSET OF NAME TABLE 
SEGMENT OF NAME TABLE 
SESSION LONG NAME 


QDNAMOFF DW 
QDNAMSEG DW 
QDLNGNAM DB 


CL i i et eT) 


DUP (?) 
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; PARAMETER LIST FOR QSBASSW 


QSRETNCD DB 0 ; RETURN CODE 
OSFXNID DB O ; FUNCTION NUMBER 
QSENVID DB O 7 ENVIRONMENT ID 
QOSSESSID DB 0 ; SESSION ID 
QOSWINDOW DBO ; WINDOW SHORT NAME 
QOSRESERV DB 0O ; RESERVED 


; PARAMETER LIST FOR READSKEY 


RKRETNCD DB 0O ; RETURN CODE 

RKFXNID DB O ; FUNCTION NUMBER 

RKSESSID DB 0 ; SESSION ID 

RKRESRV1 DB 0 ; RESERVED 

RKTASKID DW 0 ; CONNECTOR'S TASK ID 
DB 20H ; MUST BE 20H 

RKRESRV2 DB 0 ; RESERVED 

RKSCANCD DB 0 ; SCAN CODE 

RKSHIFST DB 0 ; SHIFT STATE 
DB O ; NOT USED = 01H ON RETURN 
DB 0 ; NOT USED = OOH ON RETURN 


; PARAMETER LIST STRUCTURE FOR WRITSKEY 


WRKYPARM STRUC 
WKRETNCD DB 
WKFXNID DB 
WKSESSID DB 
WKRESRV1 DB 
WKTASKID DW 
WKOPTION DB 
WKNUMKEY DB 
WKSCNCOD DB 
WKSHFST DB 
WRKYPARM ENDS 


RETURN CODE 

FUNCTION NUMBER 
SESSION ID 

RESERVED 

CONNECTOR'S TASK ID 
OPTIONS BYTE 

KEYS SENT SUCCESSFULLY 
SCAN CODE OF THE KEY 
SHIFT STATE OF THE KEY 


OO0000000 


St et et ee! eT eT 


WRKYPAR2 STRUC 

DB 8 DUP(00) 
WKLSTOFF DW 0O ; OFFSET OF LIST OF KEYSTROKES 
WKLSTSEG DW 0O ; SEGMENT OF LIST OF KEYSTROKES 
WRKYPAR2 ENDS 


; ALLOCATE STORAGE FOR THE PARAMETER LIST 


WKPARLST WRKYPARM <> 


PASSPRMT DB "ENTER PASSWORD : $' 


PASSWORD (IN ASCII) 20 CHARACTERS + 
A 1 CHARACTER OVERFLOW 


PASSWORD DB 21 DUP(?) 


we Ne 


PCTASKID DW O 7 THIS PROGRAM'S TASK ID 

NAMARRAY DB 14 ; NAME ARRAY FOR QUERYSID FUNCTION 
NUMSESS DB 0 ; NUMBER OF MATCHING SESSIONS 
SHRTNAME DB 0 ; SESSION SHORT NAME 

SESSTYPE DB 0 7 SESSION TYPE 

WSCSESID DB 0 ; SESSION ID (WSCTRL) 

SPARE DB 0 

LONGNAME DB 8 DUP(0) 7 LONG NAME OF SESSION 


Chapter 25. Sample Program1 25-13 
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WSCSTACK DB 256 DUP(0O) ; STACK FOR THE LOCKWSC TASK 
IPLSTACK DB 256 DUP(0O) ; STACK FOR THE LOCKIPL TASK 
LOCKWSID DW 0 ; LOCKWSC TASK ID 

LOCKIPID DW ‘0 ; LOCKIPL TASK ID 

KYBDNAME DB "KEYBOARD' ; PARM LIST FOR NAMESRES ON KEYBOARD 
SMGRNAME DB "SESSMGR ' ; PARM LIST FOR NAMESRES ON SESSMGR 
KEYBOARD DW 0 ; RESOLVED ID FOR 'KEYBOARD' 

SESSMGR DW 0 ; RESOLVED ID FOR 'SESSMGR ' 

WSQUEID DW 0 SVC ID OF THE KEYSTROKE QUEUE 


WSQSIZE DW 64 ; SIZE OF THE KEYSTROKE QUEUE 
WSQSEG DW 0 ; SEGMENT OF THE KEYSTROKE QUEUE 


WSQOFF DW e) OFFSET OF THE KEYSTROKE QUEUE 
WSQUEUE DB 64 DUP(?) THE KEYSTROKE QUEUE 

IPQUEID DW 0 SVC ID OF THE KEYSTROKE QUEUE 
IPQSIZE DW 64 SIZE OF THE KEYSTROKE QUEUE 


IPQSEG DW O ; SEGMENT OF THE KEYSTROKE QUEUE 
7 


IPQOFF DW 0 OFFSET OF THE KEYSTROKE QUEUE 
IPQUEUE DB 64 DUP(?) THE KEYSTROKE QUEUE 
ENDDATA DB 90H,00H,01H,00H 
; BYTES TO ENQUEUE TO SIGNAL THE TASKS TO 
; STOP 

ERRMSG DB 'ERROR. PROGRAM ABORTED.$' 
DATASEG ENDS 
STACKSEG SEGMENT STACK 

DB 256 DUP(?) 
STACKSEG ENDS 

SUBTTL MAIN 

PAGE 
CODESEG SEGMENT 'CODE' 
; ESTABLISH CONSTANTS 
BAKSPACE EQU 08H ; ASCII FOR A BACKSPACE 
BOX EQU  OB1H ; ASCII FOR A BOX 
CR EQU  ODH ; ASCII FOR A CARRIAGE RETURN 
LF EQU OAH ; ASCII FOR A LINE FEED 
SPACE EQU 20H ; ASCII FOR A SPACE 
INNOECHO EQU- 8 ; FUNCTION NUMBER FOR DOS INPUT WITH NO ECHO 
MAIN PROC FAR 


ASSUME CS:CODESEG,DS: DATASEG,SS:STACKSEG,ES : DATASEG 


MOV AX,DATASEG ; ESTABLISH ADDRESSABILITY TO THE DATA 
MOV DS,AX 
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NEXTCHAR: 


BACKUP: 


Sample Program 1 


tt A A A A ee 2 


7; PROMPT THE USER TO ENTER THE PASSWORD ;; 


ee ee ee ed 


rrervrrvrrrerorryrrerervrerererrae area ae 8 


PROMPT 


ee ee ed 


tt a Ae A ee A A A A A A A A A 


READ THE PASSWORD INTO MEMORY. USE SI TO INDEX INTO THE 
PASSWORD AREA. AFTER EACH CHARACTER IS READ STORE IT AT 
LOCATION [SI], INCREMENT SI, AND DISPLAY A BOX TO CONFIRM 


SI. IF THE CHARACTER WAS A CARRIAGE RETURN, THEN THE 


PASSWORD IS FINISHED. SAVE THE CARRIAGE RETURN AND GO ON 


aé 
af 
;; THAT A CHARACTER WAS ENTERED. IF THE CHARACTER WAS A 
td 
re 
ii 


TO LOCK THE KEYBOARD. 


. 
i 


. 
’ 


e 
/ 
. 
, 


BACKSPACE, THEN ERASE THE LAST BOX DISPLAYED AND DECREMENT; 


. 
’ 


eooeo ree eo ere ee eee eee eee ee eee ee ee eee eee eee ees e ee eee eee eee ee see ee ee eee 


~ 
~ 
~ 


LEA SI,PASSWORD ; POINT SI TO THE START OF PASSWORD AREA 
DOSFUNCT INNOECHO ; GET A CHARACTER FROM THE KEYBOARD, NO ECHO 
CMP AL ,BAKSPACE ; CHECK IF IT IS A BACK SPACE 

JE BACKUP ; IF SO, GO TO BACKUP ROUTINE 

MOV [SI] ,AL ; SAVE THE CHARACTER IN PASSWORD AREA 

INC SI 

CMP AL,CR ; CHECK IF THIS IS THE END OF THE PASSWORD 
JE LOCK ; IF SO, PROCEED TO LOCK THE KEYBOARD 
DISPLAY BOX ; DISPLAY A BOX TO CONFIRM CHAR. ENTERED 

JMP NEXTCHAR ; GET THE NEXT PASSWORD CHARACTER 


2 


Prrr)evrervrvrevrervrrvrerrvrvrererererereee eee eae ahaa ae 


77 THIS ROUTINE IS JUMPED TO WHEN THE BACKSPACE KEY IS ; 
;; PRESSED WHILE ENTERING THE PASSWORD. IT ALLOWS THE ; 
;; USER TO MAKE CORRECTIONS WHILE ENTERING THE PASS- ; 
;; WORD. THE ROUTINE BACKS UP THE POINTER TO THE PASS-; 
77 WORD BY ONE CHARACTER AND ERASES THE LAST BOX DIS- ; 
;; PLAYED TO THE SCREEN. A CHECK IS MADE TO SEE IF THE; 
;7 PASSWORD POINTER IS ALREADY AT THE START OF THE 
7; PASSWORD BUFFER TO PREVENT BACKING THE POINTER PAST ; 
7; THE START OF THE BUFFER. ; 


Ce 2 


| a A ee A De A A A A A A 


- 
~ 
~ 


CMP SI,OFFSET PASSWORD ; CHECK IF WE'RE ALREADY AT THE START 


JLE NEXTCHAR ; IF SO, SKIP BACKING UP 

DEC SI ; POINT TO THE PREVIOUS CHARACTER 
DISPLAY BAKSPACE ; ECHO A BACKSPACE TO THE SCREEN 
DISPLAY SPACE ; ERASE THE LAST CHARACTER 
DISPLAY BAKSPACE ; ECHO A BACKSPACE TO THE SCREEN 


JMP NEXTCHAR 


oer ese ere ere eee eee eee ee ere eee eee er ee ee eee wm ee ee we we ee wwe He Be Hee ew 


prerervrrrrervrrererrerwrrereerereaeeaeaeaheeeeaeeeeaee eae 


, ! ’ 
; LOCK THE WSCTRL KEYBOARD SO THE USER CAN'T JUMP TO ;; 
; ANOTHER SESSION. LOCK OUT THE PC IPL SEQUENCE TO ;; 
; PREVENT THE USER FROM RESTARTING THIS PC SESSION. 77 


CD 


Ce A a A Ae Ae Ae OO A A A A 2 A A A A J A 


Chapter 25. Sample Program 1 


tr A A A A A A Ae Ae A ee ee A A A 
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LOCK: CALL CLEAR ; CLEAR THE SCREEN 
OSTASK ; FIND THE TASK ID OF THIS PC PROGRAM 
MOV PCTASKID,DX ; SAVE THE TASK ID IN PCTASKID 
CHEK4ERR 


NAMESRES SMGRNAME,SESSMGR 
; FIND THE RESOLVED ID FOR 'SESSMGR ' 
CHEK4ERR 


NAMESRES KYBDNAME,KEYBOARD 
; FIND THE RESOLVED ID FOR 'KEYBOARD' 
CHEK4ERR 


eee eeceee eee ee ec eee eee ee ee ee we eee eee eee eee ewe ee ee ee ee eee eee ew 


CA A Ae Ae A A A A A A A A 


av i 
7; SET UP THE KEYSTROKE QUEUE AND CONNECT TO THE WSCTRL ;; 
7; KEYBOARD FOR THE LOCKWSC TASK. ; 


Ce ee ee ee ee J 


[A A A A A Ae a A A A A A A A A A A A 


QUERYSID SESSMGR,NAMARRAY,0OOH,O1H 
; GET THE SESSION ID FOR WSCTRL 
CHEK4ERR QDRETNCD 


MOV WSQSEG,SEG WSQUEUE ; INITIALIZE VARIABLES FOR KEY- 
MOV WSQOFF,OFFSET WSQUEUE ; BOARD QUEUE OFFSET AND SEGMENT 


CRTSQ WSQSEG,WSQOFF,WSQSIZE 

; CREATE A QUEUE TO RECEIVE KEYSTROKES 
MOV  WSQUEID,DX ; SAVE THE KEYSTROKE QUEUE ID 
CHEK4ERR 


CONNSKEY KEYBOARD,WSCSESID,WSQUEID 
; CONNECT TO WSCTRL KEYBOARD 
CHEK4ERR CKRETNCD 


Ce ee ed 


Ct A A Ae A A A A A A A A A A A 


a7 
i; SET UP THE KEYSTROKE QUEUE AND CONNECT TO THE PC ;; 
i; KEYBOARD FOR THE LOCKIPL TASK. it 


a 


rProvrrrevvrrrervrrerwrereovrerere eee hea ae ae ahaha aah eae eae eae haat 


QSBASSW SESSMGR ; GET THE SESSION ID FOR THIS PC SESSION 
CHEK4ERR QSRETNCD 


MOV IPQSEG,SEG IPQUEUE : INITIALIZE VARIABLES FOR KEY- 
MOV IPQOFF,OFFSET IPQUEUE ; BOARD QUEUE OFFSET AND SEGMENT 


CRT$Q IPQSEG,IPQOFF,IPQSIZE 

; CREATE A QUEUE TO RECEIVE KEYSTROKES 
MOV IPQUEID,DX ; SAVE THE KEYSTROKE QUEUE ID 
CHEK4ERR 


CONNSKEY KEYBOARD,QSSESSID,IPQUEID 
; CONNECT TO PC KEYBOARD 
CHEK4ERR CKRETNCD 


ed 


;; CREATE THE TASKS TO LOCK OUT WSCTRL AND THE PC IPL KEYS ;; 
;; SET THE TASKS AT A HIGHER PRIORITY (59) THAN THIS MAIN ;; 
;; TASK (60) SO THAT THEY CAN BE GIVEN CONTROL WHEN IT IS ;; 
7; TIME TO CLEAN UP. i 


Ce ee Sd 


te rr A ae Ae ee Ae Se A A A A A A A A A A A A 
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TRYAGAIN: 


NXTPCHAR: 


Sample Program 1 


CRTSTASK LOCKWSC, ,WSCSTACK,00H,59,LOCKWSID 

; CREATE THE TASK TO INTERCEPT WSCTRL KEYS 
MOV LOCKWSID ,DX ; SAVE THE TASK ID IN LOCKWSID 
CHEK4ERR 


CRTSTASK LOCKIPL,,IPLSTACK,00H,59,LOCKIPID 

; CREATE THE TASK TO INTERCEPT PC IPL KEYS 
MOV LOCKIPID,DX ; SAVE THE TASK ID IN LOCKIPID 
CHEK4ERR 


ese eee eee eee eee eee eee er ee ee eee 


(At At a A 2 2 
;; START THE TASKS RUNNING ;; 


cooceerw eee er eer ee ae ee eee ee ee eee ee 


roe rvrvrerwrvre~evrewrvrvrerererereseaeeeaeeaeaeaeaeaes 


SETSRDY LOCKWSID,0O0H 
; SET THE TASK RUNNING (NO WAIT) 
CHEK4ERR 


SETSRDY LOCKIPID,0OOH 
; SET THE TASK RUNNING (NO WAIT) 
CHEK4ERR 


Cr ed 


tt Ar A A A A A A A Ae A A A A A A A A 
7; READ IN KEYSTROKES AND CHECK FOR THE PASSWORD SEQUENCE ;; 


ed 


Ct re A re Ae A A A A A A A A A 


PROMPT ; PROMPT THE USER FOR THE PASSWORD 

LEA SI ,PASSWORD ; POINT SI TO THE START OF THE PASSWORD 
DOSFUNCT INNOECHO ; READ A KEY WITHOUT ECHOING IT 

CMP AL, [SI] ; CHECK IF IT MATCHES THE PASSWORD CHAR. 
JNE TRYAGAIN ; IF NOT, START OVER 

INC SI ; POINT TO THE NEXT CHARACTER 

CMP BYTE PTR [SI],CR ; CHECK IF WE'RE AT END OF THE PASSWORD 
JNE NXTPCHAR ; IF NOT, CHECK NEXT PASSWORD CHARACTER 


ee ed 


Sr a Ar A Ae Ae A A A A A A A 


77 THE CORRECT PASSWORD WAS ENTERED. START THE CLEAN UP. ; 
;; SEND A 90H SCAN CODE TO THE TASKS TO TELL THEM TO QUIT. 
77 RETURN TO THE DISPATCHER AFTER EACH 90H SCAN CODE IS 
77 SENT TO A TASK. THE TASKS WILL GET CONTROL AFTER A : 
;; RETURN TO THE DISPATCHER SINCE THEY ARE RUNNING AT A ; 
;7 HIGHER PRIORITY THAN THIS MAIN TASK. ; 
7; DISCONNECT THE TASKS FROM THEIR RESPECTIVE KEYBOARDS, ; 
77 DELETE THE KEYSTROKING QUEUES THAT WERE CREATED FOR ; 
;; EACH TASK, DELETE THE TASKS FROM THE SYSTEM, AND CLEAR ; 
7; THE SCREEN. ; 


coroeo er weer ewe eee eee ewe eee wm weer eee eee eee eee eee eee eee eee ee ee ee eee eevee 


A Ar A A A 2 ee A A Oe A ee A J 


~ 
~ 


ENQUEUE 4,WSQUEID,ENDDATA 
7 SEND THE DATA TO SIGNAL THE END TO THE 
: LOCKWSC TASK 
CHEK4ERR 
DISPSRET OOH 7 RETURN TO THE DISPATCHER TO GIVE THE TASK 
: CONTROL SO IT CAN PROCESS THE DATA 


ENQUEUE 4,IPQUEID,ENDDATA 
; SEND THE DATA TO SIGNAL THE END TO THE 
; LOCKIPL TASK 

CHEK4ERR 
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DISPSRET OOH ; RETURN TO THE DISPATCHER TO GIVE THE TASK 
: CONTROL SO IT CAN PROCESS THE DATA 
DISCSKEY KEYBOARD,WSCSESID 
; DISCONNECT THE LOCKWSC TASK FROM WSCTRL 
CHEK4ERR DKRETNCD 
DISCSKEY KEYBOARD,QSSESSID 
; DISCONNECT THE LOCKIPL TASK FROM THIS PC 
; SESSION 
CHEK4ERR DKRETNCD 
DELSENT WSQUEID ; DELETE THE LOCKWSC KEYSTROKE QUEUE 
CHEK4ERR 
DELSENT IPQUEID ; DELETE THE LOCKIPL KEYSTROKE QUEUE 
CHEK4ERR 
DELSENT LOCKWSID ; DELETE THE LOCKWSC TASK 
CHEK4ERR 
DELSENT LOCKIPID ; DELETE THE LOCKIPL TASK 
CHEK4ERR 


CLEAR THE SCREEN BEFORE EXITING 
RETURN TO DOS 


CALL CLEAR ; 
MOV AX,4COOH ; 
INT 21H 


FINISH: 


PROCEDURE 
FUNCTION 
CLEAR THE PC SCREEN. 


CLEAR 


et et et TS 


; ESTABLISH CONSTANTS 


SETCURS EQU 02H ; BIOS SET CURSOR FUNCTION NUMBER 
VIDSTAT EQU  OFH ; BIOS GET VIDEO STATE FUNCTION NUMBER 
WRITCHAR EQU OAH ; BIOS WRITE CHARACTER WITHOUT ATTRIBUTE 
CLEAR PROC NEAR 

MOV AH,VIDSTAT ; GET THE STATE OF THE SCREEN 

INT 10H 

MOV DX,0000H ; MOVE CURSOR TO HOME POSITION 

MOV AH,SETCURS 

INT 10H 

MOV AL,SPACE ; DISPLAY A SCREENFUL OF BLANKS 

MOV CX,2000 ; 25 X 80 = 2000 BLANKS 

MOV  AH,WRITCHAR 

INT 10H 

RET 
CLEAR ENDP 
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at a al ST el it ST nt ee, Ty eT et eT eS eT 


CHECKERR 


ERROR: 


CHECKERR 


MAIN 


al Si at it Si! et a Bal eT 


LOCKWSC 


GETWSKEY: 


PROCEDURE : CHECKERR 
FUNCTION 


Sample Program 1 


THIS PROCEDURE IS PASSED TWO RETURN CODES IN CL AN BL. 
BL CONTAINS A RETURN CODE FROM THE FIRST BYTE IN A PARAMETER 
LIST. BOTH CL AND BL ARE CHECKED FOR O'S. IF EITHER CONTAINS 
A NON-ZERO RETURN CODE, AN ERROR MESSAGE IS DISPLAYED AND THE 


PROGRAM IS TERMINATED. 


NOTE : THIS IS A VERY SIMPLE ERROR HANDLER USED TO PRESERVE 
PROGRAM FLOW AND IS NOT LISTED AS AN EXAMPLE OF AN 
APPROPRIATE ERROR HANDLER. THIS ERROR HANDLER SIMPLY 
TERMINATES THE PROGRAM WHEN AN ERROR IS ENCOUNTERED 
LEAVING ANY RESOURCES, SUCH AS FIXED LENGTH QUEUES, 
PRESENTATION SPACES, AND A CONNECTION TO THE WINDOW 
SERVICES, STILL ALLOCATED. A MORE APPROPRIATE ERROR 
HANDLER WOULD DELETE ALL RESOURCES BEFORE TERMINATING. 


PROC NEAR 


CMP CL,0 
JNE ERROR 


CMP  BL,O 
JNE ERROR 


RET 


LEA  DX,ERRMSG 
DOSFUNCT DISPSTR 


JMP FINISH 


ENDP 


ENDP 


SUBTTL LOCKWSC 
PAGE 


PROCEDURE : LOCKWSC 
FUNCTION 


=e 


~e 


CHECK THE RETURN CODE IN CL 


CHECK THE RETURN CODE PASSED IN BL 


RETURN TO THE CALLER 


DISPLAY THE ERROR MESSAGE 


TERMINATE THE PROGRAM AND EXIT TO DOS 


THIS PROCEDURE IS KICKED OFF AS A SEPARATE TASK. ITS JOB 
IS TO INTERCEPT AND DISCARD ALL WSCTRL KEYSTROKES. THIS 
PREVENTS THE USER FROM ACCESSING THE WSCTRL FUNCTIONS. 

THIS TASK WILL STOP INTERCEPTING KEYS AND SET ITSELF 


"UNREADY" WHEN IT READS A 90H SCAN CODE. 


SIGNAL FROM THE MAIN TASK TO STOP PROCESSING. 


PROC 


READSKEY KEYBOARD,WSCSESID, PCTASKID 


CMP RKSCANCD , 90H 
JE WSFINISH 


JMP GETWSKEY 


° 
! 


° 
1 


me Ne Me Ne 


GRAB A KEYSTROKE OUT OF THE QUEUE WHEN 
ONE IS READY 


CHECK FOR THE SCAN CODE THAT SIGNALS THE 
END 

IF SO, QUIT READING KEYSTROKES AND SET 
THIS TASK UNREADY 

TRY FOR ANOTHER KEYSTROKE. 
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A 90H SCAN CODE IS A 
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WSFINISH: 


LOCKWSC 


ot it iT Me! St eT eT eT eT ee) eT | eT eS eT eT a Td 


SETUNRDY LOCKWSID,0OOH 
; SET THIS TASK UNREADY (NO WAIT) 


ENDP 


SUBTTL LOCKIPL 
PAGE 


PROCEDURE : LOCKIPL 
FUNCTION : 

THIS PROCEDURE IS KICKED OFF AS A SEPARATE TASK. ITS JOB IS TO 
INTERCEPT AND DISCARD THE PC IPL KEY SEQUENCE (CTRL - ALT - DEL). 
THIS PREVENTS THE USER FROM RE-IPLING THE PC SESSION. , 

THIS IS ACCOMPLISHED BY READING THE PC KEYSTROKES AND CHECKING 
FOR THE CTRL-ALT-DEL KEYSTROKE. THIS KEYSTROKE IS DROPPED WHILE ALL 
OTHERS ARE WRITTEN BACK TO THE PC SESSION. 

THE BREAK KEYSTROKES ARE NOT SENT BACK TO THE PC SESSION SINCE 
THE WRIT_KEY API SERVICE WILL TAKE CARE OF SENDING BREAK KEYSTROKES 
TO THE PC SESSION. HOWEVER, ANY BREAK KEYSTROKES SENT THROUGH THE 
API SERVICE WILL NOT AFFECT THE KEYSTROKING IN THE PC SESSION. BY 
DROPPING THE BREAK KEYSTROKES THE SPEED OF THIS ROUTINE IS IMPROVED. 

THIS TASK WILL STOP INTERCEPTING KEYS AND SET ITSELF "UNREADY" 
WHEN IT READS A 90H SCAN CODE. A 90H SCAN CODE IS A SIGNAL FROM THE 
MAIN TASK TO STOP PROCESSING. 


; ESTABLISH CONSTANTS 


DEL_SCAN 
CTRL 

ALT 
LOCKIPL 


GETPCKEY: 


MAKEKEY : 
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3270 PC SCAN CODE FOR THE DELETE KEY 
SHIFT STATE FOR CTRL KEY PRESSED 
SHIFT STATE FOR ALT KEY PRESSED 


EQU 71H 
EQU  00001000B 
EQU 00000100B 


et ee 1 


PROC 


READ_KEY KEYBOARD,QSSESSID,PCTASKID 
; GRAB A KEYSTROKE OUT OF THE QUEUE WHEN ONE IS 
; READY 


CMP RKSCANCD,OFOH ; CHECK FOR THE "BREAK" KEYSTROKE 
JNE MAKEKEY ; IF NOT THE BREAK THEN IT IS A MAKE KEYSTROKE 


READ_KEY KEYBOARD,QSSESSID,PCTASKID 
; GET THE SCAN CODE FOR THE BREAKING KEYSTROKE 
; FROM THE QUEUE. 


JMP GETPCKEY ; GET ANOTHER KEYSTROKE 


CMP RKSCANCD,90H ; CHECK FOR THE SCAN CODE THAT SIGNALS THE END 

JNE VALIDKEY ; IF NOT, CONTINUE PROCESSING 

JMP IPFINISH ; OTHERWISE, QUIT READING KEYSTROKES AND SET THIS 
; TASK UNREADY 


Cr 


Cr A A A A A A A A A A A A A A A A A A A A A 


ae 

+; CHECK IF THIS KEYSTROKE IS A CTRL-ALT-DEL. FIRST CHECK ; 
;; IF THE SCAN CODE IS FOR A DEL KEY. IF IT IS, THEN CHECK 
37 IF THE CTRL KEY IS PRESSED. IF THE CTRL KEY IS PRESSED ; 
+; THEN CHECK IF THE ALT KEY IS ALSO PRESSED. IF THESE ; 
;; THREE CONDITIONS ARE TRUE, THEN SKIP SENDING THIS KEY- ; 
;; STROKE TO THE PC SESSION. ; 


ey 


CA A A A A A A A A A A A A A A A 


VALIDKEY: 


OKKEY: 


IPFINISH: 


LOCKIPL 


CODESEG 
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CMP RKSCANCD,DEL_SCAN ; CHECK FOR THE DEL KEY 
JNE OKKEY ; IF NOT, SEND THE KEYSTROKE TO THE PC 


TEST RKSHIFST,CTRL CHECK IF THE CTRL KEY IS PRESSED 


=e 6 


JZ OKKEY IF NOT, SEND THE KEYSTROKE TO THE PC 
TEST RKSHIFST,ALT ; CHECK IF THE ALT KEY IS ALSO PRESSED 
JZ OKKEY ; IF NOT, SEND THE KEYSTROKE TO THE PC 
JMP GETPCKEY ; GET ANOTHER KEYSTROKE 


WRIT_KEY KEYBOARD,QSSESSID,RKSCANCD,RKSHIFST,,,PCTASKID 
; SEND THE KEYSTROKE TO THE PC SESSION 


JMP GETPCKEY ; TRY FOR ANOTHER KEYSTROKE. 


SETUNRDY LOCKIPID,OOH 
; SET THIS TASK UNREADY (NO WAIT) 


ENDP 


ENDS 


END 
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PROGRAM : LOCKSWSC 


FUNCTION 

THIS PROGRAM WILL STOP A USER FROM USING THE WORK STATION 
CONTROL WINDOWING FEATURES. NOTHING WILL HAPPEN IF THE WSCTRL 
KEY IS PRESSED. THIS ALLOWS A USER TO SET UP THE SCREENS VIA 
THE RESTORE UTILITY BUT NOT TO CHANGE THE SET-UP OF THE WINDOWS 
ON THE SCREENS. 


THE USER WILL ONLY BE ALLOWED TO JUMP BETWEEN WINDOWS AND 
SCREENS, AND ENLARGE THE WINDOWS. 


THIS WILL BE IMPLEMENTED BY CREATING A TASK THAT WILL INTERCEPT 
ALL WORK STATION CONTROL KEYSTROKES AND ACCEPT ONLY THE JUMP 
AND ENLARGE KEYS. THIS PROGRAM CAN BE USED AS A_ SYSTEM 
EXTENSION. WHICH MEANS THAT THE WORK STATION CONTROL KEY IS 
DISABLED WHEN THE 3270 PERSONAL COMPUTER CONTROL PROGRAM IS 
LOADED. 


IF THIS PROGRAM IS USED AS A PC APPLICATION, AND IT IS RUN 
IN A MULTI-DOS SYSTEM, THEN IT MUST HAVE A PIF INDICATING THIS 
PROGRAM IS ALL GOOD. 
THIS PROGRAM WILL DEMONSTRATE THE FOLLOWING 
API FUNCTIONS: 
NAME RESOLUTION 
QUERY SESSION ID 
CONNECT TO THE KEYBOARD 
CREATE A FIXED LENGTH QUEUE 
CREATE A TASK 
SET READY 
READ INPUT 
WRITE KEYSTROKE 
GET REQUEST COMPLETION 
QUERY ACTIVE TASK 


; DOS FUNCTION CALLS 


DISPSTRG EQU 09H ; PRINTING A STRING 
DISPCHAR EQU 02H ; PRINTING A CHARACTER 
; CONSTANTS 
QRYSTYPE EQU OOH ; OPTION BYTE FOR QUERY ID, QUERY BY 
; SESSION TYPE 
WSCTRL EQU 01H ; DATA BYTE FOR QUERY ID,WORK STATION 
: CONTROL 
WSCTRLSK EQU 04H ; SCAN CODE FOR WORK STATION CONTROL KEY 
NONSPRE EQU O1H ; A TASK IS NON-PREEMPTABLE 
PRIO EQU 60 ; PRIORITY OF A TASK 
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NOSWAIT EQU 000000008 ; NO WAIT, TASK IS DISPATCHABLE 

STAKSSIZ EQU 512 ; SIZE OF PROGRAM STACK 

INTERCEPT EQU 01000000B ; INTERCEPT ALL KEYSTROKES FOR WS CNTRL 
; USED BY CONNECT TO THE KEYBOARD API 

ra *** MACRO DEFINITIONS *** 


MACRO NAME : NAMESRES 
PARAMETERS : NRSSERVN-- LOCATION OF THE 8 BYTE 
SERVICE NAME. I.E.'SESSMGR ' 
NRSSERVT-- RETURN THE RESOLVED VALUE FOR THE SERVICE 
FUNCTION 
USE THE NAMESRES SERVICE TO OBTAIN THE SERVICE TYPE FOR 
THE SERVICE NAME YOU SPECIFY. 


et Tt eT i) i | et eT Td 


NAMESRES MACRO NRSSERVN,NRSSERVT 


; INITIALIZE REGISTERS FOR NAMESRES 

MOV AX,SEG NRSSERVN ; SEGMENT ADDRESS OF PARM LIST 
MOV ES ,AX ; ES SEGM ADDRESS OF PARM LIST 
MOV AH, 81H ; AH », Gato 2 Nae 

MOV DI,OFFSET NRSSERVN ; DI OFFSET ADDR. OF PARM LIST 


; SIGNAL WORKSTATION PROGRAM FOR NAMESRES SERVICE 
INT 7AH 


; RETURN SERVICE TYPE ID TO CALLER 
MOV NRSSERVT, DX 
ENDM 


MACRO NAME : QSID 
PARAMETERS : QIDARRYN 


ARRAY NAME, MEMORY LOCATION NAME 


QIDOPT - OPTION BYTE 
O1H = SPECIFY SHORT OR LONG NAME 
OOH = SPECIFY A SESSION TYPE,IE PC 
QIDDATA - DATA BYTE 
O1H=WSCTL ,O2H=DFT,O3H=CUT, 
O4H=NOTEPAD,O5H=P.C,0=SPECIFY SHORT 
OR LONG NAME 
LSESSNAM - LONG SESSION NAME, MEMORY LOCATION 
NAME. THIS IS OPTIONAL. 
SERVTYPE - NAME RESOLUTION FOR SESSMGR 
QIDSRETC - THE RETURN CODE FOUND IN THE 


PARAMETER LIST (NOT IN THE CL REG.) 


FUNCTION 
USE THIS SERVICE TO OBTAIN THE SESSION ID OF THE SESSION 
YOU. SPECIFY. 


NOTE- THE NAMES ARRAY MUST BE DECLARED BY THE CALLER 
THE ARRAY LENGTH IN THE NAMES ARRAY MUST BE INITIALIZED 
BY THE CALLER. 


eT ee | eT ee) eT er nT eT nT OY eT | TT eT eT eT eT 
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QUERYSID 


we Se Ne te Se Me NO Ne Ne Ne 


MACRO 


MOV 
MOV 
MOV 
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OIDARRYN ,QIDOPT, QIDDATA, LSESSNAM , SERVTYPE , QIDSRETC 


AX,SEG QDRCODE ; ADDRESSABILITY TO 
ES , AX ; PARAMETER LIST 
DI,OFFSET QDRCODE 

; USING ES:DI 


; INITIALIZE PARAMETER LIST FOR QUERYSID 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 


MOV 


QDRCODE , 00H ; RETURN CODE = 0 ON REQUEST 
QDFXNID, 00H ; FUNCTION CODE=0 ON REQUEST 
AL, QIDOPT 

QDOPT , AL ; OPTION BYTE 

AL, QIDDATA 

QDDATA, AL ; DATA BYTE 


QDAOFF,OFFSET QIDARRYN 

; ARRAY OFFSET 
QDASEG,SEG QIDARRYN 

; ARRAY SEGMENT 


; IS THERE A LONG SESSION NAME ? 


IFNB 
CLD 
PUSH 
MOV 
MOV 


MOV 
MOV 
MOV 


REP 
POP 
ENDIF 


‘pel UP 
MOV 
MOV 
MOV 
MOV 
MOV 


<LSESSNAM> ; IF NAME IS SPECIFIED, 

; THEN BEGIN MOVING NAME 
DS ; INTO PARAMETER LIST 
CX,4 ; NAME IS FOUR WORDS LONG 
SI,OFFSET LSESSNAM 


; SOURCE OFFSET IN SI 
AX,SEG LSESSNAM 
DS, AX ; SOURCE SEGMENT IN DS 
DI,OFFSET QDLNAM 
; DESTINATION OFFSET IN DI 
MOVSW :; MOVE SESSION NAME TO PARAMETER LIST 
DS 


REGISTERS FOR QUERYSID 


AX,0901H ; AH = O9H, AL = 01H 
BX ,8020H BH = 80H, BL = 20H 
CX ,0000H CX = 0000H 


; 
DX,SERVTYPE ; SESSION SERVICE TYPE 
DI,OFFSET QDRCODE 


; OFFSET ADDRESS OF PARAM LIST 


; REQUEST QUERYSID SERVICE 


INT 


7AH 


; SEND RETURN CODE BACK TO CALLER 


MOV 
MOV 


ENDM 


BL , QDRCODE 
QIDSRETC,BL 


MACRO NAME : CONNSKEY 


PARAMETERS : SERVTYPE -- SERVICE TYPE 
SESSID -- SESSION ID 
KEYSTQ  -- KEYSTROKE QUEUE ID (OPTIONAL) 
EVNTQ -- EVENT QUEUE ID (OPTIONAL) 
OPT -- RECEIVE ALL, SOME OR NO KEYSTROKES 
FUNCTION 


CONNECT THE KEYBOARD TO THE SPECIFIED SESSION. 
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CONNSKEY 


et et ee eS ee eS eT eT TT eT eT) 


CRTSQ 
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MACRO SERVTYPE,SESSID,KEYSTQ,EVNTQ, OPT 


; INITIALIZE PARAMETER LIST FOR CONNSKEY 

MOV CKRETNCD, 00H ; RETURN CODE MUST = O BEFORE REQUEST 
MOV CKFXNID,OOH ; FUNCTION ID MUST = O BEFORE REQUEST 
MOV AL,SESSID ; SESSION ID INTO THE LIST 

MOV  CKSESSID,AL 

MOV AL,OPT ; OPTION BYTE INTO LIST 

MOV  CKOPTION,AL 

IFNB <KEYSTQ> 

MOV AX,KEYSTQ ; IF A KEYSTROKE QUEUE WAS SPECIFIED, 
ELSE ; PUT IT INTO THE LIST 

MOV AX,0 

ENDIF 


MOV CKKEYSTQ,AX 


IFNB <EVNTQ> 


MOV AX ,EVNTQ ; IF AN EVENT QUEUE WAS SPECIFIED, 
ELSE ; PUT IT INTO THE LIST 

MOV AX,0 

ENDIF 


MOV CKEVENTO , AX 


; INITIALIZE REGISTERS FOR CONNSKEY 

MOV AH,09H 

MOV AL,O1H 

MOV BH,80H 

MOV BL,20H 

MOV CX,0O000H 

MOV DX,SERVTYPE ; SERVICE TYPE IN DX 

MOV DI, SEG CKRETNCD ; SEGMENT ADDRESS OF PARAMETER LIST 
MOV &ES,DI ; IN ES 

MOV DI,OFFSET CKRETNCD ; OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR CONNSKEY SERVICE 
INT 7AH 


ENDM 


MACRO NAME : CRTSQ 


PARAMETERS : Q -~- Q IS THE MEMORY LOCATION NAME 
FOR THE QUEUE 
QNAME -- QNAME IS THE USERS NAME FOR THE 


NEWLY CREATED QUEUE. QNAME IS 
OPTIONAL. CRTSQ EXPECTS QNAME TO BE 
REFERENCED BY THE DS REGISTER 
NUMBYTES -- NUMBER OF BYTES IN THE QUEUE 
RETSID -- CRT$Q RETURNS THE QUEUES ID 
FUNCTION : 
USE THE CRT$Q SERVICE TO CREATE A FIXED LENGTH QUEUE 
ENTRY. ; 


MACRO Q,QNAME ,NUMBYTES ,RETSID 


MOV AX,SEG CQQOFFS ; ADDRESSABILITY TO 
MOV ES ,AX ; PARAMETER LIST 
MOV DI,OFFSET CQQOFFS ; USING ES:DI 


ek ee ee et eT eT ey a eT eT ee Ty 


CRTSTASK 


REP 
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; INITIALIZE FIRST 2 ENTRIES OF PARAMETER LIST 
MOV CQQOFFS,OFFSET Q ; OFFSET OF QUEUE 
MOV CQOSEGM,SEG Q ; SEGMENT OF QUEUE 


; USER SPECIFY A QUEUE NAME? 
IFNB <QNAME> 
MOV BL,O1H 


IF THERE IS A QUEUE NAME THEN 
INDICATE A QNAME IS SPECIFIED 


CLD ; BEGIN MOVING QNAME TO THE PARAM LIST 
MOV Cx, 4 ; QNAME IS FOUR WORDS LONG 

MOV SI,OFFSET QNAME ; SOURCE OFFSET OF QUEUE 

MOV DI,OFFSET CQQNAME;DESTINATION OFFSET IS CQQNAME 

REP MOVSW ; MOVE QNAME TO PARAMETER LIST 

ELSE 

MOV BL, OOH ; ELSE INDICATE QNAME IS NOT SPECIFIED 
ENDIF 

; INITIALIZE REGISTERS FOR CRTSQ 

MOV CX ,NUMBYTES ; CX = NUMBER OF BYTES FOR QUEUE 

MOV AH, 04H 

MOV DI,OFFSET CQQOFFS;DI = OFFSET OF PARAM LIST 

; SIGNAL WORKSTATION PROGRAM FOR CRTSQ SERVICE 

INT 7AH 

MOV RETSID,DX ; RETURN THE QUEUE ID TO CALLER 

ENDM 


MACRO NAME : CRISTASK 


PARAMETERS : TASK -- TASK TO BE CREATED 
NAME -- NAME OF THE TASK 
STACK -- STACK FOR THE TASK 
PREEMPT -- PREEMPTION TYPE 
PRIORITY -- PRIORITY OF THE TASK 
DATA -- A DATA ITEM IN DATASEG ACCESSED BY THE 


TASK IN ORDER TO PUT THE DATA SEG IN 
TASKS STACK 
FUNCTION 
CREATES A TASK 


MACRO TASK,NAME,STACK, PREEMPT, PRIORITY ,DATA 


; INITIALIZE PARAMETER LIST FOR CRTSTASK 

MOV AX,OFFSET STACK GET THE OFFSET OF THE TASK'S STACK 

ADD AX ,232 INCREMENT THE SP TO POINT AT THE 
START OF REGISTER RESTORE AREA 

PUT TASK'S SP IN PARAMETER LIST 

PUT TASK'S SS IN PARAMETER LIST 


MOV CTTSKOFF,AX 
MOV AX,SEG STACK 
MOV CTTSKSEG,AX 


- Oe Ne Se Ne Ne 


BL = 0 IF NO NAME SPECIFIED 

IF THERE IS A NAME SPECIFIED, PUT 
IT IN THE PARAMETER LIST 

BL = 1 IF A NAME IS SPECIFIED 

ES:DI POINT TO DESTINATION IN PARM 
LIST 


MOV BL,O 
IFNB <NAME> 


MOV BL,1 

MOV AX,SEG CTTSKNAM 
MOV ES,AX 

MOV DI,OFFSET CTTSKNAM 
MOV SI,OFFSET NAME 


se Se Se Ne Ne Ne 


DS:SI POINT TO SOURCE OF THE NAME 


MOV CxX,8 ; MOVE 8 BYTES 
MOVSB ; COPY THE NAME INTO THE PARM LIST 
ENDIF 
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; INITIALIZE THE TASK'S STACK 


PUSH DS ; SAVE DS 

MOV AX,SEG STACK ; GET THE TASK'S STACK SEGMENT 

MOV DS,AX 

MOV SI,OFFSET STACK ; DS:SI NOW POINT TO THE TASK STACK 


MOV WORD PTR [SI+254] ,OF242H 
; SET FLAGS IN THE STACK 
MOV AX,SEG TASK 
MOV WORD PTR [SI+252] ,AX 
; SET SEGMENT OF TASK IN STACK 
MOV AX,OFFSET TASK 
MOV WORD PTR [SI+250] ,AX 
; SET OFFSET OF TASK IN STACK 
MOV AX,SEG DATA 
; YOU NEED THE DATA SEGMENT 
MOV WORD PTR [SI+234] ,AX 
; TO GET TO THE VARIABLES 
POP DS ; RESTORE DS 


; INITIALIZE REGISTERS FOR CRTSTASK 

MOV AH , 92H : 

MOV BH, PREEMPT ; PREEMPTION TYPE IN BH 

MOV CX,PRIORITY 3; PRIORITY IN CX 

MOV DI, SEG CTTSKOFF 3; SEGMENT ADDRESS OF PARAMETER LIST 
MOV ES,DI ; IN ES 

MOV DI,OFFSET CTTSKOFF ; OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR CRTSTASK SERVICE 
INT 7AH 


ENDM 


MACRO NAME : SETSRDY 


PARAMETERS : REPLYTYP -- REPLY TYPE 
WAITTYPE -~- WAIT TYPE 
PRIORITY -- PRIORITY 
SERVTYPE -- SERVICE TYPE 
SESSID. -- SESSION ID 
FUNCTION 


SET THE SPECIFIED TASK TO THE "READY" STATE. 


MACRO TASKID,WAITTYPE 


; INITIALIZE REGISTERS FOR SETSRDY 

MOV AH ,02H ; 

MOV BL ,WAITTYPE ; WAIT TYPE IN BL 
MOV DX, TASKID ; TASK ID IN DX 


; SIGNAL WORKSTATION PROGRAM FOR SETSRDY SERVICE 
INT 7AH 


ENDM 


Se i eT a) et eT eT 


READSKEY 


Se) et ee eT ee et eT TY 


WRITSKEY 


“MOV DI, SEG RKRETNCD 
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MACRO NAME : READSKEY 


PARAMETERS : SERVTYPE -- SERVICE TYPE 

SESSID -- SESSION ID 

TASKID -- ID OF TASK (OPTIONAL) 
FUNCTION 


THIS SERVICE READS KEYSTROKE DATA FROM A SESSION. 


MACRO SERVTYPE,SESSID,TASKID 


; INITIALIZE PARAMETER LIST FOR READSKEY 

MOV RKRETNCD , OOH RETURN CODE MUST = O BEFORE REQUEST 
MOV RKFXNID,OOH FUNCTION ID MUST = O BEFORE REQUEST 
MOV AL ,SESSID SESSION ID INTO THE LIST 

MOV RKSESSID,AL 

IFNB <RKTASKID> 


me Ne Ne 


MOV  AX,TASKID ; IF A TASK ID WAS SPECIFIED, PUT IT 
ELSE : IN THE LIST, ELSE PUT IN A 0 
MOV AX,0 

ENDIF 


MOV  RKTASKID,AX 


; INITIALIZE REGISTERS FOR READSKEY 

MOV AH,09H 

MOV AL,03H 

MOV BH,80H 

MOV BL,20H 

MOV CX,OFFH 

MOV DX,SERVTYPE ; SERVICE TYPE IN DX 
; SEGMENT ADDRESS OF PARAMETER LIST 

MOV £ES,DI ; IN ES 

MOV DI,OFFSET RKRETNCD ; OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR READSKEY SERVICE 
INT 7AH 


ENDM 


MACRO : WRITSKEY 


PARAMETERS : SERVTYPE -- SERVICE TYPE 

SESSID -- SESSION ID 

SCANCD -- SCAN CODE 

SHIFST -- SHIFT STATE 

LISTOFF -- LIST OFFSET (OPTIONAL) 

LISTSEG -- LIST SEGMENT (OPTIONAL) 

TASKID -- CONNECTOR'S TASK ID (OPTIONAL) 
FUNCTION 


SEND A KEYSTROKE OR A LIST OF KEYSTROKES TO THE 
SPECIFIED SESSION. 


MACRO SERVTYPE,SESSID,SCANCD,SHIFST,LISTOFF,LISTSEG,TASKID 
LOCAL WKEND 


WKRETCD MUST BE O FOR THE CALL 
WKFXNID MUST BE O FOR THE CALL 
PUT THE SESSION ID IN PARM LIST 


MOV WKPARLST.WKRETNCD,0OH 
MOV WKPARLST.WKFXNID,OH 
MOV AL,SESSID 

MOV WKPARLST.WKSESSID,AL 


Sy et TY 


IFNB <SCNCD> ; CHECK IF SENDING ONE KEYSTROKE 
; OR A LIST OF KEYSTROKES 
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WKEND: 


Sy eT et eT eS ST St a i 
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; SENDING ONE KEYSTROKE 


MOV AL,SCANCD 
MOV WKPARLST.WKSCNCOD,AL 
MOV AL,SHIFST 
MOV WKPARLST.WKSHFST,AL 


MOV AL,20H 
MOV WKPARLST.WKOPTION,AL 


ELSE 


° 
, 


. 
, 


‘ 


PUT THE SCAN CODE IN THE PARM LIST 


PUT SHIFT STATE IN THE PARM LIST 


PUT THE OPTION BYTE FOR SENDING 
ONE CHARACTER IN THE PARM LIST 


; SENDING A LIST OF KEYSTROKES 


MOV AX,LISTOFF 

MOV WKPARLST.WKLSTOFF ,AX 
MOV AX,LISTSEG 

MOV WKPARLST.WKLSTSEG,AX 
MOV AL,30H 

MOV WKPARLST.WKOPTION,AL 


ENDIF 


IFNB <TASKID> 
MOV AX,TASKID 

ELSE 

MOV AX,0 

ENDIF 

MOV WKPARLST.WKTASKID,AX 


PUT THE OFFSET ADDRESS OF THE LIST 
INTO THE PARAMETER LIST 

PUT THE SEGMENT ADDRESS OF THE LIST 
INTO THE PARAMETER LIST 

PUT THE OPTION BYTE FOR SENDING A 
LIST OF CHARS. IN THE PARM LIST 


IF A CONNECTOR'S TASK ID WAS 
SPECIFIED, PUT IT IN THE LIST 


OTHERWISE PUT A O IN THE LIST 


; INITIALIZE THE REGISTERS FOR WRITSKEY 


MOV AH,O09H 

MOV AL,O4H 

MOV BH,40H 

MOV BL,40H 

MOV CX,0000H 

MOV DX,SERVTYPE 

MOV DI, SEG WKPARLST 
MOV ES,DI 

MOV DI, OFFSET WKPARLST 


INT 7AH 


CMP CL,OOH 
JNE WKEND 


GETSCOMP OOH 
NOP 


ENDM 


MACRO : GETSCOMP 
FUNCTION: 


SERVICE TYPE IN DX 

GET SEGMENT ADDRESS OF PARM LIST 
AND PUT IT IN ES 

SET DI TO OFFSET OF PARM LIST 


PASS THE REQUEST TO THE API 


CHECK FOR AN OK RETURN CODE 
IF NOT OK, SKIP GETTING RESULTS 


GET THE RESULTS. DON'T WAIT. 


USE THIS SERVICE TO OBTAIN THE CONTENTS OF A SPECIFIED 


REQUEST QUEUE ELEMENT. 


ONE PARAMETER IS PASSED THAT INDICATES WHETHER THE USER 
WANTS TO WAIT UNTIL RESULTS ARE READY (40H) OR TO CHECK IF 
RESULTS ARE AVAILABLE AND GET THEM IF THEY ARE READY (00H). 


GETS$COMP 
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MACRO WAIT 


MOV BL,WAIT 


MOV AH,83H ; SET UP THE REGS FOR A GETSCOMP CALL 
MOV CX,0000H 

INT 7AH 

ENDM 


STACKSEG SEGMENT STACK 'STACK' 


DB STAKSSIZ DUP(?) ; STACK SPACE 


STACKSEG ENDS 


DATASEG SEGMENT 'DATASEG' 


; NAMESRES PARAMETER LIST ELEMENT, SERVICE NAME 


SESSMGR 


DB 'SESSMGR ' 


KEYBOARD DB 'KEYBOARD' 


; RETURNED SERVICE TYPES FROM NAMESRES 


SMGR 
KEYB 


DW 0 
DW O 


; NAME ARRAY FORMAT FOR QSID 


LENARRAY 
MATCHES 
SNAMES1 
STYPES1 
SESSIDS1 
SPARES1 
LNAMES 1 


DB 22 ; NUMBER OF BYTES IN NAME ARRAY 

DB O ; NUMBER OF MATCHING SESSIONS 

DB O ; SHORT NAME OF MATCHING SESSION 
DB 0 ; TYPE OF MATCHING SESSION 

DB O ; SESSION ID OF MATCHING SESSION 
DB O 

DB O ; LONG NAME OF MATCHING SESSION 

DB 15 DUP(0O) 


; DEFINE PARAMETER LIST FOR QUERYSID 


QDRCODE 
QDFXNID 
QDOPT 
QDDATA 
QDAOFF 
QDASEG 
QDLNAM 


DB 
DB 
DB 
DB 
DW 
DW 
DB 


RETURN CODE 
FUNCTION ID 

OPTION BYTE 

DATA BYTE 

NAMES ARRAY OFFSET 

NAMES ARRAY SEGMENT ADDRESS 
WINDOW LONG NAME 


aodod0c000 


“oe “se Ne Me NO Ne Ne 


DUP(' ') 


; PARAMETER LIST FOR CRTSTASK 


CTTSKOFF DW O 
CTTSKSEG DW 0O 
CTTSKNAM DB 8 DUP(?) 


OFFSET OF TASK TO BE CREATED 
SEGMENT OF TASK TO BE CREATED 
TASK NAME 


me Ne Ne 
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; PARAMETER LIST FOR CONNSKEY 


CKRETNCD DB 
CKFXNID DB 
CKSESSID DB 
CKRESRV1 DB 
CKEVENTQ DW 
CKKEYSTO DW 
CKOPTION DB 
CKRESRV2 DB 


RETURN CODE 
FUNCTION NUMBER 
SESSION ID 
RESERVED 

EVENT QUEUE ID 
KEYSTROKE QUEUE ID 
OPTION BYTE 
RESERVED 


oOOoO0C00O0000 


bi et et ee) ee) eT eT) 


; PARAMETER LIST STRUCTURE FOR WRITSKEY 


WRKYPARM STRUC 
WKRETNCD DB 
WKFXNID DB 
WKSESSID DB 
WKSPARE DB 
WKTASKID DW 
WKOPTION DB 
WKNUMKEY DB 
WKSCNCOD DB 
WKSHFST DB 
WKRESRV2 DW 
WRKYPARM ENDS 
WRKYPAR2 STRUC 

DB 8 DUP(0O0) 
WKLSTOFF DW 0 
WKLSTSEG DW O 
WRKYPAR2 ENDS 


OO00CDOCOCCO00 


; ALLOCATE STORAGE FOR THE PARAMETER LIST 


WKPARLST WRKYPARM <> 


; PARAMETER LIST FOR READSKEY 


RKRETNCD DB 
RKFXNID DB 
RKSESSID DB 
RKRESRV1 DB 
RKTASKID DW 
RKOPTION DB 


RETURN CODE 

FUNCTION NUMBER 

SESSION ID 

RESERVED 

CONNECTOR'S TASK ID 

OPTION BYTE (INTERCEPT ALL) 


DCODDOONODOOCO 
O 
Ha) 


RKRESRV2 DB RESERVED 
RKSCANCD DB SCAN CODE 
RKSHIFST DB SHIFT STATE 
RKDEVID DB DEVICE ID 
RKRESRV3 DB RESERVED 


; DEFINE PARAMETER LIST FOR CRTS$Q 


CQQOFFS DW 0 
CQSEGM DW 0 
CQQNAME DB 8 DUP(' ') 


; DECLARE A STACK FOR TASK, USED BY CRTSTAST API FUNCTION 
TASKSSTK DB 256 DUP(?) 
TASKSID DW O ; TASK ID RETURNED FROM CRTSTASK 
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; CREATE AREA FOR A QUEUE, USED BY CRTSQ API FUNCTION 


QUE DB 100 DUP(?) 

LENSQ DW 100 ; LENGTH OF QUEUE 

QSID DW O 4; QUEUE ID RETURNED FROM CRTSQ 

CONNID DW O ; THE ID OF THE TASK THAT CONNECTS TO 
; WSCTRL 

RCODE DB O ; RETURN CODE FORM Q$ID PARAM LIST 
DLAST DB O ; LAST BYTE IN THE DATA SEGMENT 


DATASEG ENDS 


; *** MAIN BODY *** 


ZCODE SEGMENT 'CODE' 


; ESTABLISH ADDRESSABILITY OF CODE 
ASSUME CS : ZCODE 
; ESTABLISH ADDRESSABILITY OF DATA 


START: MOV AX ,DATASEG 
MOV DS , AX 
ASSUME DS :DATASEG 


; THE CODE THAT WILL CREATE THE TASK WILL FOLLOW THE ACTUAL 


; DEFINITION OF THE TASK 
JMP INITTSK 


*** TASK DEFINITION *** 


~ea Ne Ne 


TASK PROC FAR 
; READ A KEYSTROKE THAT IS DIRECTED TO WORK STATION CONTROL 
; NOTE: THE CONNECTOR'S ID (CONNID) IS USED BY THE READSKEY 
; FUNCTION BECAUSE THE TASK THAT REQUESTED THE CONNECT 
; TO WORK STATION CONTROL IS DIFFERENT FROM THE TASK THAT 
} IS REQUESTING THE READ KEYSTROKE. 
READKEYS: READSKEY KEYB,SESSID$1,CONNID 


; IF THE KEYSTROKE IS FOR WORK STATION CONTROL THEN IGNORE 
; IT AND READ THE NEXT KEYSTROKE. 

CMP RKSCANCD ,WSCTRLSK 

JE READKEYS 


; THE KEYSTROKE MUST BE THE ENLARGE WINDOW OR JUMP KEY. 

; SEND THE KEYSTROKE TO WORK STATION CONTROL TO BE PROCESSED. 

; NOTE: THE CONNECTOR'S ID (CONNID) IS USED BY THE WRITSKEY 

; FUNCTION BECAUSE THE TASK THAT REQUESTED THE CONNECT 

; TO WORK STATION CONTROL IS DIFFERENT FROM THE TASK THAT 
; IS REQUESTING THE WRITE KEYSTROKE. 

WRITSKEY KEYB,SESSID$1,RKSCANCD,RKSHIFST, , ,CONNID 


; CONTINUE READING KEYSTROKES 
JMP READKEYS 


TASK ENDP 
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: *** TNITIALIZATION CODE *** 


; REQUEST THE NAME RESOLUTION FOR THE SESSION MANAGER 
INITTSK: NAMESRES SESSMGR,SMGR 


; REQUEST THE NAME RESOLUTION FOR THE KEYBOARD 
NAMESRES KEYBOARD,KEYB 


; GET THE SESSION ID FOR WORK STATION CONTROL 
QUERYSID LENARRAY ,QRYSTYPE,WSCTRL, ,SMGR,RCODE 


; CREATE A QUEUE IN ORDER TO BE ABLE TO INTERCEPT WSCTRL KEYS 
CRTSQ QUE, ,LENSQ,Q$ID 


FIND OUT THE TASK ID OF THE INITIALIZATION CODE. 

THIS IS THE ID OF THE TASK THAT IS CONNECTING TO 

WORK STATION CONTROL. THIS ID WILL BE NEEDED LATER TO 
; READ AND WRITE KEYSTROKES. 

MOV AH , 9CH ; QUERY ACTIVE TASK REQUEST 


eT eT) 


INT 7AH 
MOV CONNID,DX ; SAVE TASK'S ID ON RETURN 


; CONNECT TO WORK STATION CONTROL, IN ORDER TO INTERCEPT 
; KEYSTROKES THAT ARE DIRECTED TO WORK STATION CONTROL 
CONNSKEY KEYB,SESSIDS1,Q$ID,,INTERCEPT 


; CREATE A TASK, NEWLY CREATED TASKS ARE CREATED UNREADY 
CRTSTASK TASK, ,TASKSSTK,NONSPRE,PRIO,KEYB 
MOV TASKSID,DX ; SAVE TASK ID 


; SET THE TASK READY 
SETSRDY TASKSID,NOSWAIT 


; EXIT AND STAY RESIDENT 
CALL EXITSRES 


*** PROCEDURE DEFINITION *** 


~e se Ne 


PROCEDURE : EXITSRES 

FUNCTION : 
CALCULATE THE SIZE OF THIS PROGRAM THAT WILL REMAIN RESIDENT. 
(STACK + SIZE OF TASK + DATA) 
EXIT FROM THIS PROGRAM BUT STAY RESIDENT IN MEMORY. 


SL i nt ST el Mn 
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EXITSRES PROC NEAR 


; CALCULATE THE LENGTH OF THIS PROGRAM 

MOV AX,OFFSET DLAST LENGTH OF DATA 

ADD AX, STAKSSIZ + LENGTH OF STACK 
ADD AX,OFFSET INITTSK + LENGTH OF TASK 
ADD AX, 100H + LENGTH OF THE PSP 


it it iT ey eT eT) 


MOV CL,4 CALCULATE THE LENGTH OF THIS PROGRAM 
SAR AX, CL IN PARAGRAPHS (DIVIDE BY SIXTEEN) 
INC AX ROUND UP 


STORE IN DX FOR THE DOS INTERRUPT 
DOS FUNCTION CALL TO 


MOV DX, AX 
MOV AH,31H 


“eo se Ne NO 


INT 21H EXIT & REMAIN 
RESIDENT 
EXITSRES ENDP 
ZCODE ENDS ; END .CODE SEGMENT 


END START 


Chapter 26. Sample Program2 26-13 


Sample Program 2 


26-14 


Sample Program 3 


Chapter 27. Sample Program 3 


TITLE WNDWSMRY 
PAGE 60,132 


PROGRAM : WNDWSMRY 


FUNCTION 

THIS PROGRAM PRESENTS A SUMMARY OF THE USER'S CURRENTLY 
ACTIVE SESSIONS. A SAMPLE WINDOW IS DISPLAYED FOR EACH SESSION. 
THE WINDOWS ARE DISPLAYED ACCORDING TO SESSION TYPE, FIRST THE 
PC WINDOWS, THEN THE HOST WINDOWS, THEN THE NOTEPAD WINDOWS. 
A MESSAGE IN THE LOWER LEFT CORNER TELLS THE NUMBER OF WINDOWS 
FOR THAT SESSION TYPE. THE USER IS THEN PROMPTED TO PRESS A 
KEY TO INITIATE THE PROGRAM EXIT. 

A PROBLEM ARISES IN DISPLAYING THE MESSAGE IN THE LOWER 
LEFT CORNER. ANY MESSAGE MUST BE DISPLAYED IN A WINDOW. BUT THE 
WINDOW THIS PROGRAM WILL RUN IN IS ONE OF THE SAMPLE WINDOWS TO 
BE DISPLAYED. TO SOLVE THIS, AN ALTERNATE PRESENTATION SPACE IS 
CREATED. THE MESSAGE IS DISPLAYED IN THE LOWER LEFT CORNER OF 
THE ALTERNATE PRESENTATION SPACE AND A SIZED WINDOW OF EACH OF 
THE OTHER SESSIONS IS DISPLAYED ON TOP OF THE ALTERNATE PRESEN- 
TATION SPACE. 

EACH WINDOW IS SIZED TO 4 ROWS BY 14 COLUMNS. THIS SIZING 
PERMITS 20 WINDOWS (THE MAXIMUM NUMBER OF WINDOWS ON THE 3270 
PC) TO BE DISPLAYED IN A 5 BY 4 ARRAY ON THE SCREEN. 

IN ORDER TO PRESERVE THE USER'S CURRENT WINDOW AND SCREEN 
SETUP, THE PROGRAM DOES ALL THE WORK ON AN UNUSED SCREEN 
PROFILE. A SEARCH IS MADE STARTING AT SCREEN 9 AND COUNTING 
DOWN FOR A SCREEN PROFILE THAT HAS NO WINDOWS. IF NO BLANK 
SCREEN IS FOUND, THEN A MESSAGE IS DISPLAYED INDICATING A BLANK 
SCREEN IS NEEDED AND THE PROGRAM ENDS. ONCE AN UNUSED SCREEN 
PROFILE IS FOUND, THE ALTERNATE PRESENTATION SPACE IS BROUGHT 
TO THAT SCREEN. THEN A SIZED AND COLORED WINDOW OF EACH OF THE 
SESSIONS IS BROUGHT TO THE SCREEN WITH THE MESSAGE IN THE ALT- 
ERNATE PRESENTATION SPACE SHOWING THE NUMBER AND TYPE OF THE 
WINDOWS BEING DISPLAYED. 


THIS PROGRAM USES THE FOLLOWING API FUNCTIONS: 


SELECT ACTIVE SCREEN 
SELECT ACTIVE WINDOW 

ADD WINDOW 

CLEAR SCREEN 

CONNECT TO WORK STATION CONTROL 
CHANGE ENLARGE STATE , 
CHANGE WINDOW POSITION ON SCREEN 
CHANGE WINDOW COLORS 

CHANGE WINDOW SIZE 

DEFINE PRESENTATION SPACE 
DISCONNECT FROM WORK STATION CONTROL 
DELETE PRESENTATION SPACE 

NAME RESOLUTION 

QUERY SESSION ID 

QUERY ACTIVE SCREEN 

QUERY ACTIVE WINDOW 

QUERY ENLARGE STATE 

QUERY BASE WINDOW 

QUERY WINDOW NAMES 


me ee Me Ne Ne Ne Se Me 8 Ne Ne Ne Ne Ne Ne Ne te Ne Se Se Ne 8 Ne NA Ne Se Ne Ne Se Ne te Ne ee He Ne Ne Me Se Ne Se Ne 8 Ne Ne NS Ne Ne Ne Ne Ne te Ne Ne Ne 
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SUBTTL CONSTANTS 


PAGE 


; ESTABLISH CONSTANTS 


CR 

LF 
DISPSTR 
INKEY 
RED 
GREEN 
BLUE 
WHITE 


St i! Tt eT ee eT eT) 


ACTSSCR 
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EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 


ae 

10 

9 

8 
00000100B 
000000108 
00000001B 
00000111B 


“we we te NO Ne Ne NO Me 


ASCII FOR 
ASCII FOR 


A CARRIAGE RETURN 
A LINE FEED 


DOS DISPLAY CHARACTER FUNCTION NUMBER 


DOS INPUT 
ATTRIBUTE 
ATTRIBUTE 
ATTRIBUTE 
ATTRIBUTE 


CHARACTER FUNCTION NUMBER 
BYTE FOR RED ON BLACK 
BYTE FOR GREEN ON BLACK 
BYTE FOR BLUE ON BLACK 
BYTE FOR WHITE ON BLACK 


SUBTTL MACROS 


; SUPPRESS LISTING ALL MACROS 


- SALL 

MACRO NAME ACTSSCR 

PARAMETERS SERVTYPE 
SESSID 
SCREEN 

FUNCTION 


-- RESOLVED VALUE FOR 
-- SESSION ID 
-~- SCREEN PROFILE NUMBER 


‘WSCTRL ' 


MAKE THE SPECIFIED SCREEN PROFILE THE ACTIVE SCREEN. 


MACRO SERVTYPE,SESSID,SCREEN 


; INITIALIZE PARAMETER LIST FOR ACTSSCR 


RETURN CODE MUST = O BEFORE REQUEST 
FUNCTION ID MUST = O BEFORE REQUEST 
SESSION ID INTO THE LIST 


SCREEN NUMBER 


ACTSSCR 


RESOLVED VALUE FOR 'WSCTRL  ' 

SEGMENT ADDRESS OF PARAMETER LIST 
IN ES 

OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR ACTS$SCR SERVICE 


MOV ASRETNCD,OOH ; 
MOV ASFXNID,OOH ; 
MOV AL,SESSID ; 
MOV ASSESSID,AL 

MOV °*AL,SCREEN : 
MOV ASSCREEN,AL 

; INITIALIZE REGISTERS FOR 
MOV AH,O9H 

MOV AL,1CH 

MOV BH, 80H 

MOV BL,20H 

MOV CX,OFFH 

MOV DX,SERVTYPE ; 
MOV DI, SEG ASRETNCD~ ; 
MOV ES,DI : 
MOV DI,OFFSET ASRETNCD ; 
INT  7AH 

ENDM 


Se eT ee) ee) en eT ey 


ACTSWNDW 
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MACRO NAME : ACTSWNDW 


PARAMETERS : SERVTYPE -- RESOLVED VALUE FOR 'WSCTRL  ' 
SESSID -- SESSION ID 
SCREEN -- SCREEN NUMBER 
WINDOW -- WINDOW SHORT NAME 


FUNCTION 
MAKE A WINDOW ON THE SPECIFIED SCREEN PROFILE THE 
ACTIVE WINDOW. 


MACRO SERVTYPE,SESSID,SCREEN ,WINDOW 


; INITIALIZE PARAMETER LIST FOR ACTSWNDW 

MOV ACRETNCD,OOH RETURN CODE MUST = O BEFORE REQUEST 
MOV ACFXNID,OOH FUNCTION ID MUST = 0 BEFORE REQUEST 
MOV AL,SESSID SESSION ID INTO THE LIST 

MOV ACSESSID,AL 
MOV AL,SCREEN 
MOV ACSCREEN,AL 
MOV AL,WINDOW ; WINDOW SHORT NAME 
MOV ACWINDOW,AL 


se Ne Ne 


SCREEN NUMBER 


™e 


; INITIALIZE REGISTERS FOR ACTSWNDW 

MOV AH,09H 

MOV AL,14H 

MOV BH,80H 

MOV BL,20H 

MOV CX,OFFH 

MOV DX,SERVTYPE ; RESOLVED VALUE FOR 'WSCTRL ' 

MOV DI, SEG ACRETNCD ; SEGMENT ADDRESS OF PARAMETER LIST 
MOV ES,DI : IN ES 

MOV DI,OFFSET ACRETNCD ; OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR ACTSWNDW SERVICE 
INT 7AH 


ENDM 


MACRO NAME : ADDSWNDW 


PARAMETERS : SERVTYPE -- RESOLVED VALUE FOR 'WSCTRL '! 
SESSID -- SESSION ID 
SCRPRO -- SCREEN PROFILE NUMBER IN ASCII 
WINDN -- WINDOW SHORT NAME IN ASCII 
FUNCTION 


ADD A WINDOW FROM SCREEN PROFILE O TO THE SPECIFIED 
SCREEN PROFILE. THE ADDED WINDOW BECOMES THE ACTIVE 
WINDOW. WINDOWS CANNOT BE ADDED TO SCREEN PROFILE 0. 


MACRO SERVTYPE,SESSID,SCRPRO,WINDN 


; INITIALIZE PARAMETER LIST FOR ADDSWNDW 
MOV AWRETNCD , OOH AWRETNCD MUST BE O BEFORE REQUEST 


MOV AL,SESSID ; SESSION ID 

MOV AWSESSID,AL ; IN LIST 

MOV AL,SCRPRO ; SCREEN PROFILE NUMBER 
MOV AWSCRPRO,AL ; IN LIST 

MOV AL,WINDN ; WINDOW SHORT NAME 
MOV AWWINDN , AL : IN LIST 


; INITIALIZE REGISTERS FOR ADDSWNDW 
MOV AH,O9H 
MOV AL,0O3H 
MOV BH,80H 
MOV BL,20H 
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MOV CX ,OFFH 

MOV DX ,SERVTYPE ; RESOLVED VALUE FOR 'WSCTRL  ' 

MOV DI, SEG AWRETNCD ; SEGMENT ADDRESS OF PARAMETER LIST 
MOV ES,DI ; IN ES 

MOV DI,OFFSET AWRETNCD ; OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR ADDSWNDW SERVICE 
INT 7AH 


ENDM 


MACRO NAME : CLEARSSC 


PARAMETERS : SERVTYPE -- RESOLVED VALUE FOR 'WSCTRL  ' 
SESSID -~- SESSION ID 
SCRPRO -- SCREEN PROFILE NUMBER IN ASCII 
FUNCTION 


DELETE ALL WINDOWS FROM THE SPECIFIED SCREEN PROFILE. 
WINDOWS CAN NOT BE DELETED FROM SCREEN PROFILE 0. 


™oe “eo “se SO NO SH NO Ne SE 


CLEARSSC MACRO SERVTYPE,SESSID,SCRPRO 


; INITIALIZE PARAMETER LIST FOR CLEARSSC 

MOV CLRETNCD , 00H CLRETNCD MUST BE O BEFORE REQUEST 
MOV CLFXNID,OOH CLFXNID MUST BE O BEFORE REQUEST 

MOV AL,SESSID SESSION ID OBTAINED FROM REQUEST 

MOV CLSESSID,AL TO QUERYSID 

MOV AL, SCRPRO SCREEN PROFILE NUMBER 

MOV CLSCRPRO,AL IN LIST 


et et et TY 


; INITIALIZE REGISTERS FOR CLEARSSC 

MOV AH ,O9H 

MOV AL,13H 

MOV BH, 80H 

MOV BL,20H 

MOV CX ,OFFH 

MOV DX, SERVTYPE ; RESOLVED VALUE FOR 'WSCTRL ' 

MOV DI, SEG CLRETNCD ; SEGMENT ADDRESS OF PARAMETER LIST 
MOV ES,DI : IN ES 

MOV DI,OFFSET CLRETNCD ; OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR CLEARSSC SERVICE 
INT 7AH 


ENDM 


MACRO NAME : CONNSWSC 
PARAMETERS : SERVTYPE -- RESOLVED VALUE FOR 'WSCTRL ' 
SESSID -~ SESSION ID 
FUNCTION : 
CONNECT TO THE WORK STATION CONTROL SESSION FOR THE WIN- 
DOW MANAGEMENT SERVICES. ONLY ONE SESSION CAN BE CONNECTED 
FOR WINDOW MANAGEMENT SERVICES AT A TIME. 


we Ne “Me Ne Ne Se Ne Ne ONO 


CONNSWSC MACRO SERVTYPE,SESSID 


; INITIALIZE PARAMETER LIST FOR CONNSWSC 


MOV CWRETNCD, OOH ; RETURN CODE MUST = O BEFORE REQUEST 
MOV CWFXNID,OOH ; FUNCTION ID MUST = O BEFORE REQUEST 
MOV AL, SESSID ; SESSION ID INTO PARAMETER LIST 


MOV CWSESSID,AL 
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; INITIALIZE REGISTERS FOR CONNSWSC 

MOV AH,O9H 

MOV AL,O1H 

MOV BH,80H 

MOV BL,20H 

MOV CX,OFFH 

MOV DX,SERVTYPE ; RESOLVED VALUE FOR 'WSCTRL ' 

MOV DI, SEG CWRETNCD ; SEGMENT ADDRESS OF PARAMETER LIST 
MOV ES,DI : IN ES 

MOV DI,OFFSET CWRETNCD ; OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR CONNSWSC SERVICE 
INT 7AH 


ENDM 


MACRO NAME : CSENLUN 
PARAMETERS : SERVTYPE -- RESOLVED VALUE FOR 'WSCTRL  ' 
SESSID -- SESSION ID 
FUNCTION 
TOGGLE THE "ENLARGE STATE" OF THE DISPLAY. AN ENLARGED 
DISPLAY BECOMES NORMAL, OR A NORMAL DISPLAY BECOMES 
ENLARGED. 


we “ee Ne we Ne Ne Ne Ne Ne 


CSENLSUN MACRO SERVTYPE,SESSID 


; INITIALIZE PARAMETER LIST FOR CSENLUN 
MOV CERETNCD , OOH CERETNCD MUST BE O BEFORE REQUEST 
MOV CEFXNID,0OOH CEFXNID MUST BE O BEFORE REQUEST 
MOV AL,SESSID SESSION ID OBTAINED FROM REQUEST 
MOV CESESSID,AL TO QUERYSID 


ue Oe Ne Me 


; INITIALIZE REGISTERS FOR CSENLUN 

MOV AH,O9H 

MOV AL,O9H 

MOV BH,80H 

MOV BL,20H 

MOV CX,OFFH 

MOV DX,SERVTYPE ; RESOLVED VALUE FOR 'WSCTRL ' 

MOV DI, SEG CERETNCD ; SEGMENT ADDRESS OF PARAMETER LIST 
MOV ES,DI ; IN ES 

MOV DI,OFFSET CERETNCD ; OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR CSENLUN SERVICE 
INT 7AH 


ENDM 


MACRO NAME : CSSCRPOS 


PARAMETERS : SERVTYPE -- RESOLVED VALUE FOR 'WSCTRL  ' 
SESSID -- SESSION ID 
SCRNUM -- SCREEN NUMBER 
WNDWNAME -- WINDOW SHORT NAME 
ROW -- ROW OF UPPER LEFT CORNER 
CcoL -- COLUMN OF UPPER LEFT CORNER 
FUNCTION 


CHANGE THE POSITION OF A WINDOW ON THE SPECIFIED SCREEN 
PROFILE. THE NEW WINDOW POSITION IS DETERMINED BY PLACING 
THE UPPER LEFT CORNER OF THE WINDOW AT THE ROW AND COLUMN 
NUMBERS SPECIFIED IN THE PARAMETER LIST. 


et eT ee et ey eT eT eT eT ee! eT et ey 
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CSSCRPOS 
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CSWNDCOL 
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MACRO SERVTYPE,SESSID,SCRNUM,WNDWNAME , ROW, COL 


; INITIALIZE PARAMETER LIST FOR CS$SCRPOS 


MOV CSRETNCD , OOH ; RETURN CODE MUST = O BEFORE REQUEST 
MOV CSFXNID,0O0OH ; FUNCTION ID MUST = O BEFORE REQUEST 
MOV AL,SESSID ; SESSION ID INTO PARAMETER LIST 

MOV CSSESSID,AL 

MOV AL, SCRNUM ; SCREEN NUMBER INTO PARAMETER LIST 
MOV CSSCREEN , AL 

MOV AL ,WNDWNAME ; WINDOW SHORT NAME INTO LIST 

MOV CSWINDOW, AL 

MOV AL , ROW ; ROW NUMBER INTO THE LIST 


MOV CSROW,AL 
MOV AL, COL 
MOV CSCOLUMN , AL 


COLUMN NUMBER INTO THE LIST 


~e 


; INITIALIZE REGISTERS FOR CSSCRPOS 

MOV AH,09H 

MOV AL,O4H 

MOV -—«iBH, 80H 

MOV BL,20H 

MOV CX,OFFH 

MOV DX,SERVTYPE ; RESOLVED VALUE FOR 'WSCTRL ' 

MOV DI, SEG CSRETNCD ; SEGMENT ADDRESS OF PARAMETER LIST 
MOV ES,DI ; IN ES 

MOV DI,OFFSET CSRETNCD ; OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR CSSCRPOS SERVICE 
INT 7AH 


ENDM 


MACRO NAME : CSWNDCOL 


PARAMETERS : SERVTYPE -- RESOLVED VALUE FOR 'WSCTRL ' 
SESSID -~- SESSION ID 
SCREEN -- SCREEN NUMBER 
WINDOW -- WINDOW SHORT NAME 
FOREGND -- FOREGROUND COLOR 
BACKGND -- BACKGROUND COLOR 
BASE -- BASE COLOR 
FUNCTION 


CHANGE THE FOREGROUND AND BACKGROUND COLORS OF A WINDOW 
ON THE SPECIFIED SCREEN PROFILE. 


MACRO SERVTYPE,SESSID,SCREEN ,WINDOW, FOREGND, BACKGND, BASE 


; INITIALIZE PARAMETER LIST FOR CSWNDCOL 


MOV CCRETNCD , OOH ; RETURN CODE MUST = O BEFORE REQUEST 
MOV CCFXNID,0O0OH ; FUNCTION DI MUST = O BEFORE REQUEST 
MOV AL, SESSID ; SESSION ID INTO LIST 

MOV CCSESSID,AL 

MOV AL, SCREEN ; SCREEN NUMBER INTO LIST 

MOV CCSCREEN , AL 

MOV AL ,WINDOW ; WINDOW SHORT NAME INTO LIST 

MOV CCWINDOW , AL 

MOV AL, FOREGND ; FOREGROUND COLOR INTO LIST 


MOV CCFORGND , AL 
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MOV AL, BACKGND BACKGROUND COLOR INTO LIST 
MOV CCBAKGND , AL 
MOV AL, BASE 


MOV CCBASE,AL 


=e 


BASE COLOR INTO LIST 


~e 


; INITIALIZE REGISTERS FOR CSWNDCOL 

MOV AH,O9H 

MOV AL,O6H 

MOV BH,80H 

MOV BL,20H 

MOV CX, OFFH 

MOV DX,SERVTYPE ; RESOLVED VALUE FOR 'WSCTRL ' 

MOV DI, SEG CCRETNCD ; SEGMENT ADDRESS OF PARAMETER LIST 
MOV ES,DI ; IN ES 

MOV DI,OFFSET CCRETNCD ; OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR CSWNDCOL SERVICE 
INT 7AH 


ENDM 


MACRO NAME CSWNDWSZ 
PARAMETERS SERVTYPE -- RESOLVED VALUE FOR 'WSCTRL ' 
SESSID -- SESSION ID 
SCRPRO -- SCREEN PROFILE NUMBER IN ASCII 
WINDOW -- WINDOW SHORT NAME IN ASCII 
ROWS -- NUMBER OF ROWS IN NEW WINDOW SIZE 
COLS -- NUMBER OF COLUMNS IN NEW WINDOW SIZE 
FUNCTION 


CHANGE THE SIZE OF A WINDOW ON A SPECIFIED SCREEN 
PROFILE. THE WINDOW'S NEW SIZE IS DETERMINED BY THE 
NUMBER OF ROWS AND COLUMNS IN THE PARAMETER LIST. 

A VALUE OF ZERO FOR EITHER THE NUMBER OF ROWS OR 
NUMBER OF COLUMNS IN THE WINDOW SIZE IS CHANGED BY THE 
WORKSTATION PROGRAM TO BE A VALUE OF ONE. 


MACRO SERVTYPE,SESSID,SCRPRO,WINDOW, ROWS , COLS 


; INITIALIZE PARAMETER LIST FOR CSWNDWSZ 


MOV CZRETNCD,OOH ; CZRETNCD MUST BE 0 BEFORE REQUEST 
MOV CZFXNID,OOH ; CZFXNID MUST BE 0 BEFORE REQUEST 
MOV  AL,SESSID ; SESSION ID OBTAINED FROM REQUEST 
MOV CZSESSID,AL ; TO QUERYSID 

MOV  AL,SCRPRO ; SCREEN PROFILE NUMBER 

MOV CZSCRPRO,AL : IN LIST 

MOV AL,WINDOW ; WINDOW SHORT NAME OBTAINED FROM 
MOV CZWINDN,AL : REQUEST TO QUERYSID 

MOV AL,ROWS ; NUMBER OF ROWS IN THE NEW 

MOV CZNUMROW,AL ; WINDOW SIZE 

MOV AL,COLS ; NUMBER OF COLUMNS IN THE 

MOV  CZNUMCOL,AL ; WINDOW SIZE 

; INITIALIZE REGISTERS FOR CSWNDWSZ 

MOV AH,09H 

MOV AL,O5H 

MOV BH,80H 

MOV BL,20H 

MOV CX,OFFH 
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Oy et eS i eT 


27-8 


MOV DX,SERVTYPE ; RESOLVED VALUE FOR 'WSCTRL ' 

MOV DI, SEG CZRETNCD ; SEGMENT ADDRESS OF PARAMETER LIST 
MOV ES ,DI ; IN ES 

MOV DI,OFFSET CZRETNCD ; OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR CSWNDWSZ SERVICE 
INT 7AH 


ENDM 


MACRO NAME : DEFINSPS 


PARAMETERS : SERVTYPE -- RESOLVED VALUE FOR 'PCPSM ‘ 
BUFFSEG -- WORK BUFFER 
PSDS -- POINTER TO PS DATA STREAM 
FUNCTION 


CREATE A NEW PRESENTATION SPACE. 


MACRO SERVTYPE,BUFFER,PSDS 


; INITIALIZE PARAMETER LIST FOR DEFINSPS 
MOV DPRETNCD , OOH ; RETURN CODE MUST 
MOV DPFXNID, OOH ; FUNCTION ID MUST 
MOV AX,OFFSET BUFFER ; 

MOV DPBUFOFF , AX 


0 BEFORE REQUEST 
0 BEFORE REQUEST 
BUFFER OFFSET INTO THE LIST 


Wet 


MOV AX,SEG BUFFER ; BUFFER SEGMENT INTO THE LIST 
MOV DPBUFSEG , AX 
MOV AX,OFFSET PSDS ; PSDS OFFSET INTO THE LIST 


‘MOV DPDSOFF , AX 


MOV AX,SEG PSDS ; PSDS SEGMENT INTO THE LIST 
MOV DPDSSEG,AX 


; INITIALIZE REGISTERS FOR DEFINSPS 

MOV AH,O9H 

MOV AL,O1H 

MOV BH,80H 

MOV BL,20H 

MOV CX,OFFH 

MOV DX,SERVTYPE ; SERVICE TYPE IN DX 

MOV DI, SEG DPRETNCD ; SEGMENT ADDRESS OF PARAMETER LIST 
MOV ES,DI ; IN ES 

MOV DI,OFFSET DPRETNCD ; OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR DEFINSPS SERVICE 
INT 7AH 


ENDM 


MACRO NAME : DISCSWSC 
PARAMETERS : SERVTYPE -- RESOLVED VALUE FOR 'WSCTRL ' 
SESSID ~- SESSION ID 
FUNCTION : 
DISCONNECT FROM THE WORK STATION CONTROL SESSION. 


DISCSWSC 
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MACRO SERVTYPE,SESSID 


; INITIALIZE PARAMETER LIST FOR DISCSWSC 

MOV DWRETNCD, OOH DWRETNCD MUST BE O BEFORE REQUEST 
MOV DWFXNID,0OOH DWFXNID MUST BE O BEFORE REQUEST 
MOV AL,SESSID SESSION ID OBTAINED FROM REQUEST 
MOV DWSESSID,AL TO QUERYSID 


™e “eNO Ne 


; INITIALIZE REGISTERS FOR DISCS$WSC 

MOV AH,O9H 

MOV AL,O2H 

MOV BH, 80H 

MOV BL,20H 

MOV CX, OFFH 

MOV DX,SERVTYPE ; RESOLVED VALUE FOR 'WSCTRL ' 

MOV DI, SEG DWRETNCD ; SEGMENT ADDRESS OF PARAMETER LIST 
MOV ES,DI ; IN ES 

MOV DI,OFFSET DWRETNCD ; OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR DISCSWSC SERVICE 
INT 7AH 


ENDM 


MACRO NAME : DSTRYSPS 
PARAMETERS SERVTYPE -- RESOLVED VALUE FOR 'PCPSM ' 
SESSID -- SESSION ID 


ee 


FUNCTION 
DELETE A PRESENTATION SPACE. 


MACRO SERVTYPE,SESSID 


; INITIALIZE PARAMETER LIST FOR DSTRYSPS 


MOV DYRETNCD, OOH ; RETURN CODE MUST = O BEFORE REQUEST 
MOV DYFXNID,0O0OH ; FUNCTION ID MUST = O BEFORE REQUEST 
MOV AL,SESSID ; HANDLE ID INTO THE LIST 


MOV DYSESSID,AL 


; INITIALIZE REGISTERS FOR DSTRYSPS 

MOV AH,O9H 

MOV AL,O2H 

MOV BH,80H 

MOV BL,20H 

MOV CX,OFFH 

MOV DX,SERVTYPE ; RESOLVED VALUE FOR 'PCPSM  '! 

MOV DI, SEG DYRETNCD ; SEGMENT ADDRESS OF PARAMETER LIST 
MOV ES,DI : IN ES 

MOV DI,OFFSET DYRETNCD ; OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR DSTRYSPS SERVICE 
INT 7AH 


ENDM 


MACRO -~ NAMESRES 
PARAMETERS - NRSSERVN - LOCATION OF THE 8-BYTE 
SERVICE NAME, I.E.'SESSMGR ' 
NRSSERVT - RETURN CODE FROM PARAMETER LIST 
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MACRO NRSSERVN ,NRSSERVT 
; SET UP REGISTERS NAMESRES 
MOV AX,SEG NRSSERVN ; SEGMENT ADDRESS OF PARM LIST 
MOV ES ,AX ; ES = SEGM ADDRESS OF PARM LIST 
MOV AH ,81H ; AH = X'81' 
MOV CX ,OOOOH ; CX = X'0000! 
MOV DI,OFFSET NR$SERVN ; DI = OFFSET ADDR. OF PARM LIST 
; REQUEST SERVICE TYPE FROM WORKSTATION PROGRAM 
INT 7AH | 
; RETURN SERVICE TYPE ID TO CALLER 
MOV NRSSERVT , DX 
ENDM 
MACRO NAME : QUERYSID 
PARAMETERS : SERVTYPE RESOLVED VALUE FOR 'SESSMGR ! 
'  NAMEARRY NAME ARRAY 
OPTION OPTION BYTE 
DATA DATA BYTE 
LONGNAME SESSION LONG NAME 
FUNCTION : 
GET THE SESSION ID(S) OF THE SESSION(S) SPECIFIED BY 
THE OPTION AND DATA BYTES AND RETURNS THEM IN THE NAME 
ARRAY. 
NOTE - THE NAME ARRAY IS SET UP BY THE USER AND MUST HAVE 
THE LENGTH OF THE ARRAY CONTAINED IN THE 1ST BYTE. 
MACRO SERVTYPE,NAMEARRY , OPTION, DATA, LONGNAME 
; INITIALIZE PARAMETER LIST FOR QUERYSID 
MOV QDRETNCD,OOH ; RETURN CODE MUST = 0 BEFORE REQUEST 
MOV QDFXNID,0OH ; FUNCTION ID MUST = 0 BEFORE REQUEST 
MOV AL,OPTION : OPTION BYTE INTO THE LIST 
MOV QDOPTION,AL 
MOV AL,DATA ; DATA BYTE INTO THE LIST 
MOV QDDATA,AL 
MOV AX,OFFSET NAMEARRY ; NAME ARRAY OFFSET INTO THE LIST 
MOV QDNAMOFF,AX 
MOV AX,SEG NAMEARRY ; NAME ARRAY SEGMENT INTO THE LIST 
MOV  QDNAMSEG,AX 
IFNB <LONGNAME> ; CHECK IF A LONG NAME WAS SPECIFIED 
CLD ; COPY DIRECTION = FORWARD 
MOV AX,SEG QDLNGNAM 
MOV ES,AX ; ES:DI POINTS TO DESTINATION IN PARM 
MOV DI,OFFSET QDLNGNAM ; LIST 
MOV SI,OFFSET LONGNAME ; DS:SI POINTS TO SOURCE OF LONG NAME 
MOV CX,8 ; MOVE 8 BYTES 
MOVSB ; COPY LONG NAME INTO THE PARM LIST 
ENDIF 


Sample Program 3 


; INITIALIZE REGISTERS FOR QUERYSID 

MOV AH,O9H 

MOV AL,O1H 

MOV BH,80H 

MOV BL,20H 

MOV CX,0000H 

MOV DX,SERVTYPE ; RESOLVED VALUE FOR 'SESSMGR ' 

MOV DI, SEG QDRETNCD ; SEGMENT ADDRESS OF PARAMETER LIST 
MOV ES,DI ; IN ES 

MOV DI,OFFSET QDRETNCD ; OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR QUERYSID SERVICE 
INT 7AH 


ENDM 


MACRO NAME : QSASCRID 
PARAMETERS : SERVTYPE -- RESOLVED VALUE FOR 'WSCTRL ' 
SESSID -- SESSION ID 
FUNCTION 
OBTAIN THE ID OF THE ACTIVE SCREEN PROFILE. 


et ee) eT ee eT 


QSASCRID MACRO SERVTYPE,SESSID 


; INITIALIZE PARAMETER LIST FOR QSASCRID 
MOV QARETNCD, OOH QARETNCD MUST BE O BEFORE REQUEST 
MOV AL ,SESSID SESSION ID OBTAINED FROM REQUEST 
MOV QASESSID,AL TO QUERYSID 


se ue MO 


; INITIALIZE REGISTERS FOR QSASCRID 

MOV AH,09H 

MOV AL,19H 

MOV BH,80H 

MOV BL,20H 

MOV CX,OFFH 

MOV DX,SERVTYPE ; RESOLVED VALUE FOR 'WSCTRL ' 

MOV DI, SEG QARETNCD ; SEGMENT ADDRESS OF PARAMETER LIST 
MOV &ES,DI : IN ES 

MOV DI,OFFSET QARETNCD ; OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR QSASCRID SERVICE 
INT 7AH 


ENDM 


MACRO NAME : QSAWNDSN 


PARAMETERS : SERVTYPE -- RESOLVED VALUE FOR 'WSCTRL ' 
SESSID ==. SESSION: 1D 
SCREEN -- SCREEN PROFILE NUMBER 
FUNCTION 


OBTAIN THE SHORT NAME OF THE ACTIVE WINDOW IN THE 
SPECIFIED SCREEN PROFILE. 


ST BT eT eT eT a eT 
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Sample Program 3 


QSAWNDSN MACRO SERVTYPE,SESSID,SCREEN 


Sl nS Mt MT TY 


QSENLSUN 
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; INITIALIZE PARAMETER LIST FOR QSAWNDSN 


MOV OQNRETNCD,OOH ; RETURN CODE MUST = O BEFORE REQUEST 
MOV QNFXNID,OOH ; FUNCTION ID MUST = O BEFORE REQUEST 
MOV AL,SESSID ; SESSION ID INTO THE LIST 

MOV OQNSESSID,AL 

MOV AL,SCREEN ; SCREEN NUMBER INTO THE LIST 


MOV QNSCREEN,AL 


; INITIALIZE REGISTERS FOR QSAWNDSN 

MOV AH,O9H 

MOV AL,18H 

MOV BH, 80H 

MOV BL,20H 

MOV CX,OFFH 

MOV DX,SERVTYPE ; RESOLVED VALUE FOR 'WSCTRL ' 

MOV DI, SEG QNRETNCD ; SEGMENT ADDRESS OF PARAMETER LIST 
MOV ES,DI ; IN ES 

MOV DI,OFFSET QNRETNCD ; OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR QSAWNDSN SERVICE 
INT 7AH 


ENDM 


MACRO NAME : QSENLSUN 
PARAMETERS : SERVTYPE -- RESOLVED VALUE FOR 'WSCTRL ' 
SESSID -- SESSION ID 
FUNCTION 
OBTAIN THE "ENLARGE STATE" OF THE DISPLAY. 


MACRO SERVTYPE,SESSID 


; INITIALIZE PARAMETER LIST FOR QSENL/UN 


MOV QERETNCD , OOH ; RETURN CODE MUST = O BEFORE REQUEST 
MOV QEFXNID,0OOH ; FUNCTION ID MUST = O BEFORE REQUEST 


MOV AL,SESSID ; SESSION ID INTO THE LIST 
MOV QESESSID,AL 7 


; INITIALIZE REGISTERS FOR QSENL/UN 
MOV AH,O9H 
MOV AL,10H 
MOV BH,80H 
MOV BL,20H 
MOV CX,OFFH ; 
MOV DX,SERVTYPE ; RESOLVED VALUE FOR 'WSCTRL ' 

MOV DI, SEG QERETNCD ; SEGMENT ADDRESS OF PARAMETER LIST 
MOV ES,DI F IN ES 

MOV DI,OFFSET QERETNCD ; OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR QSENL/UN SERVICE 
INT 7AH 


ENDM 


PT i ee) ey eT ee Ty 


QSBASSW 


Oy ey ee ee eT eT ee Ty 


QSWINDWS 


Sample Program 3 


MACRO NAME : QSBASSW 
PARAMETERS : SERVTYPE -- RESOLVED VALUE FOR 'SESSMGR ' 
FUNCTION : 

FIND THE SESSION ID AND SHORT NAME FOR THE BASE WINDOW 
OF AN ENVIRONMENT. 


MACRO SERVTYPE 
; INITIALIZE PARAMETER LIST FOR QSBASSW 


MOV QSRETNCD , 00H ; RETURN CODE MUST 
MOV QSFXNID,0O0OH ; FUNCTION ID MUST 


0 BEFORE REQUEST 
0 BEFORE REQUEST 


; INITIALIZE REGISTERS FOR QSBASSW 

MOV AH,O9H 

MOV AL,OAH 

MOV BH,80H 

MOV BL,20H 

MOV CX,OFFH 

MOV DX,SERVTYPE ; RESOLVED VALUE FOR 'SESSMGR '! 

MOV DI, SEG QSRETNCD ; SEGMENT ADDRESS OF PARAMETER LIST 
MOV ES,DI ; IN ES 

MOV DI,OFFSET QSRETNCD ; OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR QSBASSW SERVICE 
INT 7AH 


ENDM 


MACRO NAME : QSWINDWS 


PARAMETERS : SERVTYPE -- RESOLVED VALUE FOR 'WSCTRL ' 
SESSID -~ SESSION ID 
SCREEN -- SCREEN PROFILE NUMBER 
FUNCTION 


OBTAIN THE SHORT NAMES OF ALL WINDOWS IN THE SPECIFIED 
SCREEN PROFILE. 


MACRO SERVTYPE,SESSID,SCREEN 


; INITIALIZE PARAMETER LIST FOR QSWINDWS 

MOV QWRETNCD,OOH RETURN CODE MUST = 0 BEFORE REQUEST 
MOV QWFXNID,OOH FUNCTION ID MUST = 0 BEFORE REQUEST 
MOV AL,SESSID SESSION ID INTO THE LIST 

MOV QWSESSID,AL 
MOV AL,SCREEN 
MOV QWSCREEN,AL 


=e Ne Ne 


SCREEN NUMBER INTO THE LIST 


me 


; INITIALIZE REGISTERS FOR QSWINDWS 
MOV AH,O9H 

MOV AL,12H 

MOV BH, 80H 

MOV BL,20H 

MOV CX,OFFH 
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we te Ne Ne Ne 


DOSFUNCT 


Pt a eT TY 


DISPLAY 


ue “Me Me Ne ™e Ne Ne Ne Ne Oe Ne 


CHEK4ERR 
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MOV DX,SERVTYPE ; RESOLVED VALUE FOR 'WSCTRL ' 

MOV DI, SEG QWRETNCD ; SEGMENT ADDRESS OF PARAMETER LIST 
MOV ES,DI ; IN ES 

MOV DI,OFFSET QWRETNCD ; OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR QSWINDWS SERVICE 
INT 7AH 


ENDM 


MACRO : DOSFUNCT 
FUNCTION 
ISSUE THE DOS CALL WITH THE FUNCTION NUMBER PASSED IN 
FUNCTNUM 


MACRO FUNCTNUM 


MOV AH , FUNCTNUM 
INT 21H 


ENDM 


MACRO : DISPLAY 
FUNCTION 
DISPLAY THE STRING STARTING AT STRING ON THE SCREEN. 


MACRO STRING 
LEA DX, STRING 
DOSFUNCT O9H 


ENDM 


MACRO : CHEK4ERR 

FUNCTION 
SET UP THE REGISTERS FOR THE ERROR CHECKER. 
THE RETURN CODES FROM AN API FUNCTION CALL ARE IN THE CL 
REGISTER AND IN THE FIRST BYTE OF THE PARAMETER LIST. 
THE PARAMETER LIST RETURN CODE (IF IT EXISTS) IS PASSED IN 
THE PARAMETER RETCODE AND IS PASSED TO THE ERROR CHECKER 
IN BL. THE ERROR CHECKER WILL CHECK CL AND BL FOR O'S 
AND RETURN IF THEY BOTH ARE O. 


MACRO RETCODE 


IFNB <RETCODE> 


MOV BL, RETCODE ; IF A RETURN CODE FROM A PARAMETER LIST 
ELSE ; WAS SPECIFIED, PUT IT IN BL 

MOV BL,O ; OTHERWISE, SET BL TO O SO IT LOOKS LIKE 
ENDIF : A GOOD RETURN CODE TO THE ERROR CHECKER 


CALL CHECKERR 


ENDM 


~e Me Me Ne te Ne 


WRITBUFF MACRO TEXT,N,ATTRIBUT 
LOCAL NEXTCHAR 
XOR CX ,CX ; 
MOV CL,N 
LEA SI,TEXT ; 
LEA DI ,BUFFMSG ; 

NEXTCHAR: MOVSB ; 
MOV BYTE PTR [DI],AT 
INC DI ; 
LOOP NEXTCHAR ; 
ENDM 

; MACRO : BI2ASCII 

; FUNCTION 

; THE API FUNCTION CALLS. 

BI2ASCII MACRO VARIABLE 
MOV AL,VARIABLE : 
ADD AL,30H ; 
MOV VARIABLE ,AL ; 
ENDM 
SUBTTL DATA 
PAGE 

DATASEG SEGMENT 

WORKAREA DB- 1552 DUP(?) 

; PARAMETER LIST FOR ACTSSCR 

ASRETNCD DB 0 

ASFXNID DB O 

ASSESSID DB 0 

ASSCREEN DB 0 


MACR 
FUNC 


O : WRITBUFF 
TION 


Sample Program 3 


COPIES N CHARACTERS STARTING AT TEXT TO THE PS BUFFER WITH 
THE SPECIFIED ATTRIBUT (ATTRIBUTE). 


CLEAR CX TO RECEIVE THE # OF CHARACTERS 


POINT SI TO THE TEXT TO COPY 
POINT DI TO THE PS BUFFER MESSAGE AREA 


COPY A CHARACTER TO THE BUFFER 
TRIBUT 

COPY THE ATTRIBUTE INTO THE BUFFER 
POINT DI TO THE NEXT CHARACTER 


COPY. 


THE NEXT CHARACTER AND ATTRIBUTE 


CONVERTS THE VALUE IN VARIABLE - ASSUMING IT'S BETWEEN 0 
AND 9 - TO ITS ASCII EQUIVALENT BY ADDING 30H. 

THIS IS USED TO CONVERT SCREEN PROFILE NUMBERS, WHICH RANGE 
FROM O TO 9, TO THEIR ASCII EQUIVALENT WHICH IS NEEDED FOR 


; PARAMETER LIST FOR ACTSWNDW 


ACRETNCD 
ACFXNID 

ACSESSID 
ACSCREEN 
ACWINDOW 


DB 
DB 
DB 
DB 
DB 


ooO0o00 


GET THE VARIABLE BINARY VALUE 
CONVERT TO ASCII 
REPLACE VARIABLE WITH ITS ASCII VALUE 


se me Se Ne 


oe “Me Me NO Ne 


WORK AREA FOR DEFINSPS 


RETURN CODE 
FUNCTION NUMBER 
SESSION ID 
SCREEN NUMBER 


RETURN CODE 
FUNCTION NUMBER 
SESSION ID 

SCREEN NUMBER 
WINDOW SHORT NAME 
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; PARAMETER LIST FOR ADDSWNDW 


AWRETNCD DB 
AWFXNID DB 
AWSESSID DB 
AWSCRPRO DB 
AWWINDN DB 


RETURN CODE 

FUNCTION ID 

SESSION ID 

SCREEN PROFILE NUMBER IN ASCII 
WINDOW SHORT NAME IN ASCII 


oOo0o00 


; PARAMETER LIST FOR CLEARSSC 


CLRETNCD DB 
CLFXNID DB 
CLSESSID DB 
CLSCRPRO DB 


RETURN CODE 

FUNCTION NUMBER 

SESSION ID 

SCREEN PROFILE NUMBER IN ASCII 


eet exe) 


; PARAMETER LIST FOR CONNSWSC 


CWRETNCD DB 0 ; RETURN CODE 
CWFXNID DB 0 ; FUNCTION NUMBER 
CWSESSID DB _ 0 ; SESSION ID 


; PARAMETER LIST FOR CSENLUN 


CERETNCD DB 0 ; RETURN CODE 
CEFXNID DB 0 ; FUNCTION NUMBER 
CESESSID DB 0 7 SESSION ID 


; PARAMETER LIST FOR CSSCRPOS 


CSRETNCD DB 0 7 RETURN CODE 
CSFXNID DB 0O ; FUNCTION NUMBER 
CSSESSID DB 0 ; SESSION ID 
CSSCREEN DB 0 ; SCREEN PROFILE NUMBER (IN ASCIT) 
CSWINDOW DB 0 ; WINDOW SHORT NAME (IN ASCIT) 
CSROW DB 0O ; ROW NUMBER FOR POSITION OF UPPER 
: LEFT CORNER OF WINDOW 
CSCOLUMN DB 0 ; COLUMN NUMBER FOR POSITION OF UPPER 


LEFT CORNER OF WINDOW 


; PARAMETER LIST FOR CSWNDCOL 


CCRETNCD DB 
CCFXNID DB 
CCSESSID DB 
CCSCREEN DB 
CCWINDOW DB 
CCFORGND DB 
CCBAKGND DB 
CCBASE DB 


RETURN CODE 
FUNCTION NUMBER 
SESSION ID 

SCREEN NUMBER 
WINDOW SHORT NAME 
FOREGROUND COLOR 
BACKGROUND COLOR 
BASE COLOR 


~e Ne Se Ne Ne Oe NO NO 


oooooco0o00 


; PARAMETER LIST FOR CSWNDWSZ 


CZRETNCD DB 
CZFXNID DB 
CZSESSID DB 
CZSCRPRO DB 
CZWINDN DB 
CZNUMROW DB 
CZNUMCOL DB 


RETURN CODE 

FUNCTION NUMBER 

SESSION ID 

SCREEN PROFILE NUMBER IN ASCII 
WINDOW SHORT NAME IN ASCII 

NUMBER OF ROWS IN NEW WINDOW SIZE 
NUMBER OF COLUMNS IN NEW WINDOW SIZE 


oOooOoOoO0oO000 
~ ~ ~ sete NS ~ 
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; PARAMETER LIST FOR DEFINSPS 


DPRETNCD DB 
DPFXNID DB 
DPSESSID DB 
DPRESERV DB 
DPBUFOFF DW 
DPBUFSEG DW 
DPDSOFF DW 
DPDSSEG DW 

DB 
DPWINDOW DB 


RETURN CODE 

FUNCTION NUMBER 

SESSION ID 

RESERVED 

OFFSET ADDRESS OF THE 1K BUFFER 
SEGMENT ADDRESS OF THE 1K BUFFER 
OFFSET OF DATA STREAM 

SEGMENT OF DATA STREAM 

MUST BE 0 

RETURNED WINDOW SHORT NAME 


ooo eReReekenene) 


bl a Bl i i Bl Bil Sel i al} 


; PARAMETER LIST FOR DISCSWSC 


DWRETNCD DB 0O 
DWFXNID DB O 
DWSESSID DB 0 


RETURN CODE 


=e “ese Ne 


SESSION ID 


; PARAMETER LIST FOR DSTRYSPS 


DYRETNCD DB 0 ; RETURN CODE 
DYFXNID DB 0 ; FUNCTION NUMBER 
DYSESSID DB 0 ; SESSION ID 
DYRESERV DB 0 ; RESERVED 


; PARAMETER LIST FOR QUERYSID 


QDRETNCD DB 
QDFXNID DB 
QDOPTION DB 


0 RETURN CODE 
0 
0 
QDDATA DB O 
0 
0 
8 


FUNCTION NUMBER 
OPTION BYTE 

DATA BYTE 

OFFSET OF NAME TABLE 
SEGMENT OF NAME TABLE 
SESSION LONG NAME 


QDNAMOFF DW 
QDNAMSEG DW 
QDLNGNAM DB 


Se eT i i a aT 


DUP (?) 


; PARAMETER LIST FOR QSASCRID 


QARETNCD DB 0 
QAFXNID DB O 
QASESSID DB 0O 
QASCRPRO DB 0 


RETURN CODE 
FUNCTION ID 
SESSION ID 
SCREEN PROFILE NUMBER IN ASCII 


=s ‘Ne Ne ONO 


; PARAMETER LIST FOR QSAWNDSN 


RETURN CODE 

FUNCTION NUMBER 

SESSION ID 

SCREEN NUMBER 

SHORT NAME OF ACTIVE WINDOW 


QNRETNCD DB 
QNFXNID DB 
QNSESSID DB 
QNSCREEN DB 
QNWINDOW DB 


oo000 
bt i el et SL] 


; PARAMETER LIST FOR QSBASSW 


QSRETNCD DB 
QSFXNID DB 
QSENVID DB 


RETURN CODE 
FUNCTION NUMBER 
ENVIRONMENT ID 


OO0O000 
- =e ™e Se Se OO 


QSSESSID DB SESSION ID 
QSWINDOW DB WINDOW SHORT NAME 
QSRESERV DB RESERVED 
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; PARAMETER LIST FOR QSENL/UN 


QERETNCD 
QEFXNID 

QESESSID 
QEENLFLG 


; PARAMETER LIST FOR QSWINDWS 


QWRETNCD 
QWFXNID 
-QWSESSID 
QWSCREEN 
QWWNDLST 


SMGRNAME 
WSCTNAME 
PCPSNAME 


SESSMGR 
WSCTRL 
PCPSM 


SCREEN 


ROWSIZE 
COLSIZE 
ROWPOS 
COLPOS 


NAMEARRY 
NUMSESS 
SHRTNAME 
SESSTYPE 
SESSID 
SPARE 
LONGNAME 


PSDS 


PSSIZE 


PSTYPE 
SETBUFER 
BUFFOFF 
BUFFSEG 


PSBUFFER 
BUFFMSG 


NOSCRMSG 


Lore 
AREPCS 
PCSESNUM 
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DB 
DB 
DB 
DB 


DB 


DB 
DB 
DB 
DB 


DB 
DB 
DB 


DW 
DW 
DW 


DB 


DB 
DB 
DB 
DB 


DB 
DB 
DB 
DB 
DB 
DB 
DB 
DB 
DB 


DB 
DB 
DB 
DB 
DB 
DB 
DW 
DW 


DW 
DW 


DB 
DB 
DB 


DB 
DB 
DW 
DB 


ooo°o 


se Ne Ne Ne 


ey et eT ee eT eT | rT TT ee eT 


RETURN CODE 
FUNCTION NUMBER 
SESSION ID 
ENLARGE FLAG 


“ee NO Ne 


RETURN CODE 

FUNCTION NUMBER 

SESSION ID 

SCREEN NUMBER 

LIST OF WINDOW SHORT NAMES 


St et ee, eT 


PARAMETER LIST FOR NAMESRES ON "SESSMGR" 
PARAMETER LIST FOR NAMESRES ON "WSCTRL" 
PARAMETER LIST FOR NAMESRES ON "PCPSM" 


SESSION MANAGER SERVICE TYPE 
WINDOW MANAGER SERVICE TYPE 
PRESENTATION SPACE MANAGER SERVICE TYPE 


THE SCREEN WE ARE WORKING IN 


NUMBER OF ROWS IN SUMMARY WINDOWS 
NUMBER OF COLUMNS IN SUMMARY WINDOWS 
ROW POSITION OF WINDOW ON THE SCREEN 
COLUMN POSITION OF WINDOW ON THE SCREEN 


NAME ARRAY FOR QUERYSID FUNCTION 

NUMBER OF MATCHING SESSIONS 

SHORT NAME OF THE FIRST MATCHING WINDOW 

SESSION TYPE 

SESSION ID 

SPARE BYTE (UNUSED) 

LONG NAME OF THE WINDOW 

REMAINDER OF THE NAME ARRAY 

PRESENTATION SPACE DATA STREAM FOR 
DEFINSPS FUNCTION (3 COMMANDS) 

COMMAND FOR SIZE OF PRESENTATION SPACE 

25 ROWS 

80 COLUMNS 

COMMAND TO SET PRESENTATION SPACE TYPE 

PC TEXT INDIRECT (WELL BEHAVED) 

COMMAND TO SET THE PS BUFFER 

OFFSET OF THE BUFFER 

SEGMENT OF THE BUFFER 


THE PRESENTATION SPACE BUFFER 
SPACE TO DISPLAY MESSAGES (25TH LINE) 


"PROGRAM NEEDS A BLANK SCREEN PROFILE TO RUN.',CR,LF 
"DELETE ALL THE WINDOWS FROM ONE SCREEN AND TRY AGAIN.' 


"THERE IS 1 PC SESSION' 


O DUP(O) 
'SESSMGR '! 
'WSCTRL ' 
'PCPSM ' 
0 
@) 

0 

0 

4 
14 
1 

1 
170 
@) 

O 

re) 

O 

@) 
156 DUP(O) 
228 DUP(0) 
3 
O1 
25 
80 
02 
re) 
03 
0 

@) 

1920 DUP(0O) 
80 DUP(O) 
CR, LE, * S$.’ 
'THERE ARE 
0 


" PC SESSIONS' 


NOHOST 
ISHOST 
AREHOST 
HOSTNUM 


NONOTE 
ISNOTE 
ARENOTE 
NOTENUM 
NUMBRTAB 
EXITMSG 
ERRORMSG 
DATASEG 


STACKSEG 


STACKSEG 


CODESEG 


MAIN 


Sample Program 3 


DB ‘THERE ARE NO HOST SESSIONS' 

DB "THERE IS 1 HOST SESSION 

DB "THERE ARE ' 

DW 0 

DB ' HOST SESSIONS! 

DB ‘THERE ARE NO NOTEPAD SESSIONS' 

DB . 'THERE IS 1 NOTEPAD SESSION' 

DB ‘THERE ARE ' 

DW 0 

DB '" NOTEPAD SESSIONS! 

DB '0123 45 67 8 91011121314151617181920' 
DB "PRESS ANY KEY TO EXIT 

DB "ERROR. PROGRAM TERMINATED.',CR,LF,'S' 
ENDS 


SEGMENT STACK 


DB 20 DUP('STACK ') 


ENDS 


SUBTTL MAIN 


PAGE 


SEGMENT 


ASSUME CS:CODESEG,SS:STACKSEG,DS:DATASEG,ES : DATASEG 


PROC FAR 


MOV AX,DATASEG 
MOV DS,AX 


MOV ES , AX 


; ESTABLISH ADDRESSABILITY TO THE DATA 


a ee 


Cr A ie A A A A 
7; FIND THE RESOLVED VALUES FOR SESSMGR, WSCTRL, AND PCPSM ;; 


Cr ee 


Cr A A A a A A A A A A A 


NAMESRES 
CHEK4ERR 
NAMESRES 
CHEK4ERR 
NAMESRES 
CHEK4ERR 


SMGRNAME , SESSMGR 
WSCTNAME , WSCTRL 


PCPSNAME , PCPSM 


ee 


Cr A A A A ee A A A A 2 Ze 
i; FIND THE SESSION ID FOR THIS PC SESSION ;; 


Cr 


Ce A A A A A A A A A A 


QSBASSW 
CHEK4ERR 


SESSMGR 
QSRETNCD 
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FINDSCR: 


27-20 


, 


and 


MOV 
MOV 
MOV 
MOV 


eooeoenrevre ee eee eee eee eee eee ee ee ee ese wee ee ee ee ee 


| An Ae Ae A A A 2 A 2 2 2 2 A 2 2 2 2 ee 2 2 A Ze 


73 CREATE A PRESENTATION SPACE TO WORK IN ;; 


Ce ee 


[rt A A ee Ae ee A A A 2 2 2 A 2 2 2 2 A 


AX,OFFSET PSBUFFER 


BUFFOFF , AX ; PUT THE OFFSET AND SEGMENT OF THE PS 
AX,SEG PSBUFFER ; IN THE PSDS 
BUFFSEG , AX 


DEFINSPS PCPSM,WORKAREA,PSDS 


; CREATE A PRESENTATION SPACE 


CHEK4ERR DPRETNCD 


’ 


oee eee eee es ee eee ewe were were eee eee ee ee ee eee ee wm ewe weer weer eeeve 


LA a A A 


ag ay 
+; CONNECT TO WINDOW MANAGER SERVICES IN ORDER TO DO ;; 


WINDOW MANAGER API FUNCTIONS. 


ride 


coe ere eee ew ewer emer e weer e eee ere eee eee eee eee eee ere eee eee ee wee 


CA re Ae A A A A A A A A A 


CONNSWSC WSCTRL,QSSESSID 
CHEK4ERR CWRETNCD 


Ce ee) 


Ce i Ae Ae ee A A A eZ 2 2 eZ A 


‘ 


COUNT DOWN. 
MOV CX ,9 ; LOAD THE COUNT INTO CX 
MOV SCREEN ,CL ; CHECK SCREEN (COUNT) 
PUSH CX ; SAVE THE COUNT 
BI2ZASCII SCREEN ; CONVERT BINARY SCREEN NUMBER TO ASCII 
QOSWINDWS WSCTRL,OSSESSID, SCREEN 
; GET THE LIST OF WINDOWS FOR THIS SCREEN 
CMP QWRETNCD, OEH ; CHECK FOR RETURN CODE INDICATING NO 
; WINDOWS 
JE FOUNDSCR ; IF NO WINDOWS, A BLANK SCREEN WAS FOUND 
CHEK4ERR QWRETNCD 
POP CX ; RESTORE THE COUNT 


va 
7; FIND AN UNUSED SCREEN PROFILE. START WITH SCREEN 9 AND 


LOOP FINDSCR ; CHECK THE NEXT SCREEN PROFILE 


ee ee 


CA A A A A A A A A A A 


IF NO UNUSED SCREEN WAS FOUND, CLEAN UP BY DISCONNECTING 


FROM WINDOW MANAGER SERVICES AND DELETING THE NEW PRE- 


SENTATION SPACE. THEN PRINT AN ERROR MESSAGE INDICATING 
A BLANK SCREEN PROFILE IS NEEDED AND EXIT TO DOS. 


Cr ee 


Ce ee ee A A A A eZ 2 A ZZ Ze Ze 2 2 A A 2 A A 2 


DIS 


CHE 
DST 


CHE 
DIS 


JMP 


CSWSC WSCTRL,QSSESSID 

7 DISCONNECT FROM WINDOW SERVICES 
K4ERR DWRETNCD 
RY$PS PCPSM,DPSESSID 

; DESTROY THE PRESENTATION SPACE 
K4ERR DYRETNCD 
PLAY NOSCRMSG ; DISPLAY THE ERROR MESSAGE 


° 


FINISH ; EXIT TO DOS 


FOUNDSCR: 


ISNTENL: 


DONE: 


Sample Program 3 


everest se ereeeevees eee eee eee ee ee ee eee eee eee ee ee eee eer eee ew eee ee we eee ee oO 


tr a Ar A A 2 i i 2 A 2 Ae A A 2 ee A A A 


; HAVING FOUND AN UNUSED SCREEN PROFILE, SAVE THE CURRENT ;; 
; ACTIVE SCREEN PROFILE AND WINDOW. QUERY THE ENLARGE er 
; STATE OF THE DISPLAY AND SET IT TO "UNENLARGED" IF IT IS ;; 
; NOT ALREADY UNENLARGED. (THE DISPLAY MUST BE UNENLARGED  ;; 
; IN ORDER FOR THE SAMPLE WINDOWS TO SHOW) ACTIVATE THE a 
; UNUSED SCREEN PROFILE AND ADD THE WORK WINDOW TO THE - 
; SCREEN. ii 


oer ere ere eee eee seer ee see ewe ere eee ee ere eee se ee ee wee wee eee eee eee eee eee ee ee 


QSASCRID WSCTRL,QSSESSID 
; SAVE THE CURRENT ACTIVE SCREEN 
CHEK4ERR QARETNCD 
QSAWNDSN WSCTRL,QSSESSID,QASCRPRO 
; SAVE THE CURRENT ACTIVE WINDOW 
CHEK4ERR QNRETNCD 
QSENLSUN WSCTRL,QSSESSID,QASCRPRO 
; CHECK THE "ENLARGE STATE" OF THE DISPLAY 
CHEK4ERR QERETNCD 
CMP QEENLFLG,O ; IF THE DISPLAY IS NOT ENLARGED, THEN 
JE ISNTENL ; DON'T TOGGLE THE ENLARGED STATE. 
CSENLSUN WSCTRL,QSSESSID,QASCRPRO 
; TOGGLE THE ENLARGE STATE OF THE DISPLAY 
; TO UNENLARGE IT. 
CHEK4ERR CERETNCD 
ACTSSCR  WSCTRL,QSSESSID,SCREEN 
; MAKE THE BLANK SCREEN ACTIVE 
CHEK4ERR ASRETNCD 
ADDSWNDW WSCTRL,QSSESSID,SCREEN , DPWINDOW 
; ADD THE WORK WINDOW TO THE SCREEN 
CHEK4ERR AWRETNCD 
CALL PCWNDWS ; DISPLAY A SIZED WINDOW OF EACH PC SESSION 
CALL HSTWNDWS ; DISPLAY A SIZED WINDOW OF EACH HOST 
; SESSION 
CALL NOTWNDWS ; DISPLAY A SIZED WINDOW OF EACH NOTEPAD 
; SESSION 


oerecer ere eee 


ee 


| re A ee ee A ee A A 


77 PROMPT THE USER TO INITIATE THE CLEANUP AND EXIT ;; 


2 


yr re A A A A A A A A A A 


WRITBUFF EXITMSG,30,WHITE 
; WRITE THE MESSAGE TO THE PS BUFFER 
ACTSWNDW WSCTRL,QSSESSID,SCREEN , QSWINDOW 
; MAKE THIS PC WINDOW THE ACTIVE WINDOW SO 
i THAT THE DOS KEY INPUT WILL COME TO 
; THIS PC SESSION 
CHEK4ERR ACRETNCD 
DISCSWSC WSCTRL,QSSESSID 
; DISCONNECT FROM WINDOW SERVICES TO SHOW 
; THE CHANGES TO THE SCREEN 
CHEK4ERR DWRETNCD 
MOV AH, INKEY ; WAIT FOR THE USER TO HIT A KEY 
INT 2148 
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WASNTENL: 


FINISH: 


A eT eS eT ee eT eT ST eT TT eT aT 


27-22 


eeoeecerere ee eee eer eee se see see see er eee eee ee ee ee wm we ee wee ee ee wm eee wee ee ee ow 


;; CLEAN UP BY DESTROYING THE PRESENTATION SPACE THAT WAS 73 
;; CREATED, DELETING ALL WINDOWS FROM THE SCREEN, MAKING THE; ; 
;; ORIGINAL WINDOW AND SCREEN ACTIVE AGAIN, AND RESTORING 77 
7; THE ENLARGE STATE OF THE DISPLAY. 77 


eeereecece eee eee eee eee eee ee ee ee we eee eee eee ee eee eee ere eee eee ee ee ee eo 


te Ae ee Ae ee A A A A 


DSTRYSPS PCPSM,DPSESSID 
; DESTROY THE PRESENTATION SPACE THAT WAS 
: CREATED FOR A WORK SPACE 

CHEK4ERR DYRETNCD 


CONNSWSC WSCTRL,QSSESSID 
; CONNECT FOR WINDOW MANAGER SERVICES TO 
; THE WINDOW AND SCREEN THAT WERE ACTIVE 
; ON ENTRY TO THIS PROGRAM 
CHEK4ERR CWRETNCD 
CLEARSSC WSCTRL,QSSESSID,SCREEN 
; DELETE THE WINDOWS FROM THE SCREEN 
CHEK4ERR CLRETNCD 
ACTSSCR WSCTRL,QSSESSID,QASCRPRO 
; MAKE THE ORIGINAL SCREEN PROFILE ACTIVE 
CHEK4ERR ASRETNCD 
ACTSWNDW WSCTRL,QSSESSID,QASCRPRO, QNWINDOW 
; MAKE THE ORIGINAL WINDOW ACTIVE 


CMP QEENLFLG,0O ; IF THE DISPLAY WAS NOT ENLARGED, SKIP 
JE WASNTENL ; TOGGLING IT BACK TO ENLARGED STATE 


CSENLSUN WSCTRL,QSSESSID 
; TOGGLE THE DISPLAY BACK TO THE ENLARGED 
; STATE 

CHEK4ERR CERETNCD 


DISCSWSC WSCTRL,QSSESSID 
; DISCONNECT FROM WINDOW MANAGER SERVICES 
CHEK4ERR DWRETNCD 
MOV AX,4COOH ; RETURN TO DOS 
INT 21H 


PROCEDURE : PCWNDWS 
CALLED BY : MAIN 
FUNCTION : ; 

THIS PROCEDURE DISPLAYS A MESSAGE TELLING THE NUMBER OF PC 
SESSIONS AND DISPLAYS A SIZED WINDOW OF EACH PC SESSION. 
FIRST IT GETS A LIST OF THE CURRENT PC SESSIONS BY USING THE 
QUERY SESSION ID API FUNCTION ON THE SESSION TYPE FOR PC'S 
(50a Jive IT THEN DISPLAYS A MESSAGE IN THE CREATED WORK 
PRESENTATION SPACE INDICATING THE NUMBER OF PC SESSIONS. EACH 
WINDOW IN THE LIST IS ADDED TO THE SCREEN PROFILE THEN SIZED 
AND MOVED TO THE PROPER POSITION. SINCE THE CREATED WORK PS 
IS ALSO RETURNED IN THIS LIST, A CHECK IS MADE FOR THE WORK 
WINDOW. WHEN IT IS ENCOUNTERED, THE WORK WINDOW IS NOT SIZED 
OR MOVED SINCE IT WAS NOT A CURRENT PC SESSION WHEN THE PROGRAM 
WAS STARTED. 


PCWNDWS 


ONEPC: 


DISPCWN: 


NXTPCWND: 


Sample Program 3 


CO ed 


prrererrrevrerererererreeeaeaeaeaeaeeae eee 
;; GET A LIST OF THE CURRENT PC SESSIONS. ;; 


eee er ere eee ee eee weer eee we ee ee wee eee eee eee eee ee eee 


Cr A A ee A A A A A A A A 2 A 2 2 ee 


QUERYSID SESSMGR,NAMEARRY ,OOH,05H 
CHEK4ERR QDRETNCD 
; GET A LIST OF THE PC SESSIONS 


MOV AL,NUMSESS ; GET THE NUMBER OF MATCHING SESSIONS 
SUB AL,1 ; SUBTRACT 1 FOR OUR WORK WINDOW 

; CHECK IF THERE IS ONLY ONE SESSION 

; IF SO, DISPLAY THE MESSAGE FOR ONE PC 


Cr ee) 


| a ee ee Ae A A A Ze 2 A ZZ 2 


7; DISPLAY THE MESSAGE FOR MULTIPLE PC SESSIONS ;; 


eoeceee ee eee ee ee ee ew we eee wee HOH eT ee ee ee ew ee we we ee we ee ew wee ow 


te Ae ee ee A A A ee 2 A 


XOR BX,BX ; CLEAR BX TO READ THE NUMBER OF SESSIONS 
MOV BL,NUMSESS 

SUB BL,1 ; SUBTRACT 1 FOR OUR WORK WINDOW 

ADD BX, BX ; CALCULATE THE INDEX INTO THE ASCITI 


; TRANSLATION TABLE 
MOV AX,WORD PTR NUMBRTAB[BX] 
; GET THE ASCII VALUE OF THE NUMBER 
MOV PCSESNUM , AX ; PUT ASCII FOR THE NUMBER IN THE MESSAGE 
WRITBUFF AREPCS,24,BLUE 
; WRITE THE MESSAGE TO THE PS BUFFER 
JMP DISPCWN 


eoeceevr eee se eee eee ete eee eee ere sw ewe eee ewes eee eee eee 


07 at et eZ 2 2 2 2 2 2 2 2 2 
7; DISPLAY THE MESSAGE FOR ONE PC SESSION ;; 


oee es eeeer ee ere eee ee se ee ee we ee ee eH eo we ee He oO oe ee ee ew 6 


Cr Ae A A Ae A Ae A A A A A A A A A Ae A A A J J 2 A A A 2 2 ee A A 


WRITBUFF ISPC,21,BLUE 
; WRITE THE MESSAGE TO THE PS BUFFER 


Oe 


TTT TTR RT RET ETT TET ETE ETE TE ETT ETT aaa 


adr f 
;; REDRAW THE CHANGES MADE TO THE SCREEN. CHANGES TO THE :3 
;; SCREEN BY THE WINDOW MANAGER SERVICES ARE NOT SHOWN UNTIL ;; 
;; A PROGRAM EITHER DISCONNECTS FROM WINDOW MANAGER SERVICES ;; 
;;7 OR USES THE REDRAW SCREEN FUNCTION. p42 


ee ee) 


| ae Ze 2 ZZ 2 2 2 ZZ 222 22 2 2 2 2 2 2 22 22 2 
CALL DISPWNDX 


eeceeree ee ee eee ee ewe ee wee ee ee ese eer eee eee eee ree ee eee ee ee 


Cr A A A A A A A A i A A A A A ee A ee A A A A A 2 2 


;; DISPLAY THE PC WINDOWS ON THIS SCREEN PROFILE ;; 


ee er er ee er 


| rr A A A Ae A Ae A A A A A A ee ee A A A ee eZ 


XOR CX, Cx ; CLEAR CX BEFORE LOADING ONE BYTE 
MOV CL,NUMSESS ; LOAD CX WITH THE NUMBER OF PC SESSIONS 
LEA SI ,SHRTNAME ; POINT SI TO THE FIRST SESSION SHORT NAME 


MOV AL , DPWINDOW ; CHECK IF IT'S OUR CREATED WORK WINDOW 
CMP [SI] ,AL 


JE SKIPWNDX ? ITF IT IS; SKIP IT 

PUSH CX ; SAVE THE COUNT OF THE WINDOWS 
CALL ADDNMOV ; SIZE AND MOVE THE WINDOW 

POP Cx ; RESTORE THE COUNT 
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SKIPWNDX: ADD 2 ie Be, ; POINT TO THE NEXT SHORT NAME 
LOOP NXTPCWND ; DISPLAY THE NEXT PC WINDOW 
RET 


PCWNDWS ENDP 


PROCEDURE : HSTWNDWS 
CALLED BY : MAIN 
FUNCTION : 

THIS PROCEDURE DISPLAYS A MESSAGE TELLING THE NUMBER OF 
HOST WINDOWS AND DISPLAYS A SIZED AND COLORED SAMPLE WINDOW OF 
EACH HOST SESSION. 

HOST SESSIONS CAN BE EITHER CUT OR DFT; BOTH TYPES OF SESSIONS 

MUST BE QUERIED. FIRST A QUERY IS MADE FOR A CUT TYPE SESSION. 
IF THERE IS A CUT SESSION, THEN A MESSAGE IS DISPLAYED TELLING 

THERE IS ONE HOST SESSION. IF THERE IS NOT A CUT SESSION, THEN 
A QUERY IS MADE FOR ANY DFT SESSIONS AND THE NUMBER OF SESSIONS 
IS DISPLAYED. A SAMPLE WINDOW OF EACH HOST SESSION (IF ANY) IS 
ADDED TO THE SCREEN PROFILE AND THEN COLORED RED AND SIZED AND 

MOVED TO ITS PROPER POSITION. 


“eo ue we Ne te Ne Ne NO Ne Me NB Ne MO Ne NO NO 


HSTWNDWS PROC 


oer eer eee oer see eee eee eee eee see eee ere eee ee eee ewe eee ee eee eee ee eee se 


| fa A Ae A A Ae A ee A A A A 


;; SET THE ROWPOS AND COLPOS VARIABLES SO THAT THE HOST ;; 
77 SESSION WINDOWS WILL BE DISPLAYED ON THE NEXT ROW. ae 


Prryrrrrrvrrrrrrrrvreerere rear ae aeeaeeaeeaeaeeaeeaeeaeeaeaeeaeaeeaeaeaeeaeeaeeaeeaeeeeaeeeeaeaeeaeeaeaeeaeae gt 


MOV COLPOS,1 ; START AT THE FIRST COLUMN 
ADD ROWPOS , 6 ; START A NEW ROW 


ee ee 


errerevrrrevrrerrrerevrrerereraerae ease ae ae ae aaah eae ae eaeaeaeeaheeaeeahaeeeeaeaeaheaaaE 


;; GET A LIST OF THE HOST SESSIONS. FIRST CHECK FOR A CUT ie: 
7; HOST SESSION. IF THERE IS NO CUT SESSION, THEN CHECK FOR ;; 
77 ANY DFT HOST SESSIONS. ; 


oes ereeoese eee ee ere seer eee eee see eee er see eee ee ere eee eee ee eee eee se ee we we ew ee wo 


Ce 


Ut a a Ae De 2 ee 2 2 2 2 2 2 2 2 2 2 
;; CHECK FOR A CUT HOST SESSION. ;; 


eer ees ea ee ewe ewe eee eee ee eee eee eee ee ee ere 


te Ae Ae ee A A A 


QUERYSID SESSMGR,NAMEARRY ,OOH ,03H 

; GET THE LIST FOR A CUT HOST SESSION 
CMP QDRETNCD,11H ; CHECK IF THERE IS NOT A CUT SESSION 
JE CHECKDFT ; IF SO, CHECK FOR DFT HOST SESSIONS 


CHEK4ERR QDRETNCD 


JMP ONEHOST ; IF THERE IS A CUT SESSION, DISPLAY THE 
: MESSAGE FOR ONE HOST SESSION. 


oeererev eevee ee ere eee eee eee e eee eee ere ee eee ee 


rreorrerreorerrrererreer eee eee 
;; CHECK FOR ANY DFT HOST SESSIONS. ;; 


coer ere eee ee eee ewe emer wee ee ewe wm eee ee ee ee ews eee 


Ce A A A A A ee A A A A 
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CHECKDFT: 


DISPHOST: 


ONEHOST: 


MANYHOST: 


DISHSTWN : 


NXTHSTWN : 


HSTWNDWS 


Sample Program 3 


QUERYSID SESSMGR,NAMEARRY,0OH,02H 

; GET A LIST OF THE HOST DFT SESSIONS 
CMP QDRETNCD,11H ; CHECK IF THERE ARE NO DFT SESSIONS 
JNE DISPHOST 


Ce ee ee ee 


rroveorvrrerervrrrerererrere eevee 
7; DISPLAY THE MESSAGE FOR NO HOST SESSIONS ;; 


eee eee eee eer ee ee ee eee we ewe se ee eee sweater wae ee erase ses oe & 


CA rr A A A A A A A A A A A A A A A A Oe A 2 ee A A A SZ A 2 2 


WRITBUFF NOHOST,26,RED 

; WRITE THE MESSAGE TO THE PS BUFFER 
CALL DISPWNDX ; DISPLAY THE MESSAGE 
JMP NOTEPAD 


CHEK4ERR QDRETNCD 


CMP NUMSESS,1 ; CHECK IF THERE IS ONLY ONE SESSION 
JNE MANYHOST 


Cr ee | 


Cr A a A Ae A A A A A A A A eZ 
+7 DISPLAY THE MESSAGE FOR ONE HOST SESSION ;; 


Ce ee? 


Prerrvrevrourrervrvrrvrrererrvevrrrerrererrorwrerereseae ahahaha 


WRITBUFF ISHOST,24,RED 
; WRITE THE MESSAGE TO THE PS BUFFER 
JMP DISHSTWN 


eee eee eee eee ee eee ewer eee eee eee eee eee eee wee eee eee eee aes 


| re A Ae A A A A 2 J J 


;; DISPLAY THE MESSAGE FOR MULTIPLE HOST SESSIONS ;; 


Cr 


tt A A A re A A A 


XOR BX, BX ; CLEAR BX TO READ THE NUMBER OF SESSIONS 
MOV BL,NUMSESS 
ADD BX ,BX ; CALCULATE THE INDEX INTO THE ASCII 


; TRANSLATION TABLE 
MOV AX,WORD PTR NUMBRTAB[BX] 
; GET THE ASCII VALUE OF THE NUMBER 
MOV HOSTNUM , AX ; PUT ASCII FOR THE NUMBER IN THE MESSAGE 
WRITBUFF AREHOST,26,RED 
; WRITE THE MESSAGE TO THE PS BUFFER 


CALL DISPWNDX ; DISPLAY THE MESSAGE 


Cr ee 


Van ae 2a 2 2 2 2 2 ZZ 2 2 22 2 ZZ 2 2D 22 2 2 2 2 2 22 2 2 2 2 
77 DISPLAY THE HOST WINDOWS ON THIS SCREEN PROFILE ;; 


Cr 


Pprorerrvvrrrvrrerevrerrrevrerervrerererereraeaeeaeaeaehe aaah eee 


XOR CX ,CX ; CLEAR CX BEFORE LOADING ONE BYTE 
MOV CL,NUMSESS ; LOAD CX WITH THE NUMBER OF HOST SESSIONS 
LEA SI, SHRTNAME 7 POINT SI TO THE FIRST SESSION SHORT NAME 


PUSH CX i SAVE THE COUNT OF THE WINDOWS 
CALL ADDNMOV SIZE AND MOVE THE WINDOW 
CSWNDCOL WSCTRL /QSSESSID, SCREEN, [SI] ,2,0,0 
7 SET WINDOW COLOR - RED FORE, BLACK BACK 
CHEK4ERR CCRETNCD 
POP CX ; RESTORE THE COUNT 
ADD pop ae 9 ; POINT TO THE NEXT SHORT NAME 
LOOP NXTHSTWN ; DISPLAY THE NEXT HOST WINDOW 
RET 
ENDP 
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PROCEDURE : NOTWNDWS 
CALLED BY : MAIN 
FUNCTION : 

THIS PROCEDURE DISPLAYS A MESSAGE TELLING THE NUMBER OF 
NOTEPAD SESSIONS AND DISPLAYS A COLORED SAMPLE WINDOW OF EACH 
SESSION. FIRST IT GETS A LIST OF THE NOTEPAD SESSIONS BY 
USING THE QUERY SESSION ID API FUNCTION WITH THE SESSION TYPE 
FOR NOTEPAD (X'04'). A SAMPLE WINDOW OF EACH NOTEPAD (IF ANY) 
IS ADDED TO THE SCREEN PROFILE, COLORED GREEN, AND SIZED AND 
MOVED TO ITS PROPER POSITION. 


Se i) a eT eT eS eT | et TY 


NOTWNDWS PROC 


eeceeeee 2 ee ee 


[i Ae A A A A A A A A A A A A A A A 


av 
7; SET THE ROWPOS AND COLPOS VARIABLES SO THAT THE NOTEPAD ; 
77 SESSION WINDOWS ARE DISPLAYED ON THE NEXT ROW. 


ee ee ee es 


CA Ar A ee A A A A A A A A A A A A A A 


NOTEPAD: MOV COLPOS ,1 ; START AT THE FIRST COLUMN 
ADD ROWPOS,6 ; START A NEW ROW 


ee er 


i A Ae A A A A A A A A A A A A Ze 


;; GET A LIST OF THE NOTEPAD SESSIONS. ;; 


Oe ee eS ee 


te A ee A A A A A A A A 


QUERYSID SESSMGR,NAMEARRY,OOH,04H 
CMP QDRETNCD,11H ; CHECK IF THERE ARE NO NOTEPAD SESSIONS. 
JNE DISPNOTE 


ee 


Cr A A A A ee A A A 2 A A ZA 


7; DISPLAY THE MESSAGE FOR NO NOTEPAD SESSIONS ;; 


ee 


Cr A A A Ae A A A A A A A A 


WRITBUFF NONOTE,29,GREEN 

; WRITE THE MESSAGE TO THE PS BUFFER 
ACTSWNDW WSCTRL,QSSESSID,SCREEN ,QSWINDOW 

; MAKE THIS PC WINDOW THE ACTIVE WINDOW 
CHEK4ERR ACRETNCD 
CALL DISPWNDX ; DISPLAY THE MESSAGE 
JMP DONE 


DISPNOTE: CHEK4ERR QDRETNCD 
; GET A LIST OF THE NOTEPAD SESSIONS 


CMP NUMSESS,1 ; CHECK IF THERE IS ONLY ONE SESSION 
JNE MANYNOTE 


Ca a ee 


Cr A A A a A A A A A A A A A A A A A A 
;; DISPLAY THE MESSAGE FOR ONE NOTEPAD SESSION ;; 


Ce ee ee 


Cr a A Ae ee A A A A A A A A A 


WRITBUFF ISNOTE,26,GREEN 
; WRITE THE MESSAGE TO THE PS BUFFER 
JMP DISNOTWN 


Ce 


cr Ar re Ae Ae Ae A Ae A A A A A A A A A 
;; DISPLAY THE MESSAGE FOR MULTIPLE NOTEPAD SESSIONS ;; 


Cr 


Ce re Ae Ae ee ee A A A A A A 2 
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MANYNOTE: 


DISNOTWN : 


NXTNOTWN : 


NOTWNDWS 


St eS et ee ee ee eT en Td 


ADDNMOV 


Sample Program 3 


XOR BX, BX ; CLEAR BX TO READ THE NUMBER OF SESSIONS 
MOV BL,NUMSESS 
ADD BX ,BX ; CALCULATE THE INDEX INTO THE ASCII 


; TRANSLATION TABLE 
MOV AX,WORD PTR NUMBRTAB[BX] 

; GET THE ASCII VALUE OF THE NUMBER 
MOV NOTENUM,AX ; PUT ASCII FOR THE NUMBER IN THE MESSAGE 
WRITBUFF ARENOTE,29,GREEN 

; WRITE THE MESSAGE TO THE PS BUFFER 
ACTSWNDW WSCTRL,QSSESSID, SCREEN, QSWINDOW | 

; MAKE THIS PC WINDOW THE ACTIVE WINDOW 
CHEK4ERR ACRETNCD 
CALL DISPWNDX 


Ce ee ee 


rPrvrvrererrvrererrerrerervreere reer 
;; DISPLAY THE NOTEPAD WINDOWS ON THIS SCREEN PROFILE ;; 


oot e eo eee ere eee eee ee eee ee ewe eee we ee eee eee eee ee ee ee ee se ewe eee 


Ce A A Ae ee A A A 


XOR CxX7oxX ; CLEAR CX BEFORE LOADING ONE BYTE 

MOV CL,NUMSESS ; LOAD CX WITH NUMBER OF NOTEPAD SESSIONS 
LEA SI ,SHRTNAME ; POINT SI TO THE FIRST SESSION SHORT NAME 
PUSH CX ; SAVE THE COUNT OF THE WINDOWS 

CALL ADDNMOV ; SIZE AND MOVE THE WINDOW 


CSWNDCOL WSCTRL,QSSESSID,SCREEN,[SI],4,0,0 
; SET WINDOW COLOR - GREEN FORE,BLACK BACK 
CHEK4ERR CCRETNCD 
POP CX ; RESTORE THE COUNT 
ADD  SI,12 ; POINT TO THE NEXT SHORT NAME 
LOOP NXTNOTWN ; DISPLAY THE NEXT NOTEPAD WINDOW 


RET 


ENDP 


PROCEDURE : ADDNMOV 
FUNCTION 
GIVEN A SHORT WINDOW NAME POINTED TO BY SI, ADD THE WINDOW 
TO THE CURRENT WORK SCREEN. NEXT, SIZE THE WINDOW TO ROWSIZE 
BY COLSIZE. THEN MOVE THE WINDOW TO ITS POSITION ON THE SCREEN 
SPECIFIED BY ROWPOS AND COLPOS. REDRAW THE SCREEN TO SHOW 
THE CHANGES. UPDATE ROWPOS AND COLPOS FOR THE NEXT WINDOW. 
THIS PROCEDURE ASSUMES THAT A CONNSWSC HAS ALREADY BEEN 
ISSUED BY THE CALLING PROCEDURE. 


PROC NEAR 


ADDSWNDW WSCTRL,QSSESSID,SCREEN, [ST] 

; ADD THIS NOTEPAD WINDOW TO THE SCREEN 
CHEK4ERR AWRETNCD 
CSWNDWSZ WSCTRL,QSSESSID,SCREEN, [SI] ,ROWSIZE,COLSIZE 

; SIZE THE WINDOW TO ROWSIZE X COLSIZE 
CHEK4ERR CZRETNCD 
CSSCRPOS WSCTRL,QSSESSID,SCREEN, [SI] ,ROWPOS ,COLPOS 

; MOVE THE WINDOW TO ROWPOS,COLPOS 
CHEK4ERR CSRETNCD 
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ee ee 


tA ae Ae Ae a ee A A 2 A J A 


aa af 
7; UPDATE THE ROW POSITION AND THE COLUMN POSITION FOR THE ;; 
7; NEST WINDOW ia 


eoeoeoerewe ee eee eee see eee eo ee eer wee eee ere ewe eee ee ee eer ees ee eee eer eee eee se 


| Zn Ae A A ee A A A A A A 


CMP COLPOS ,65 ; CHECK IF THIS IS LAST WINDOW ON THE ROW 
JGE NEWROW ; IF SO, START A NEW ROW 
ADD COLPOS , 16 ; POINT COLPOS TO THE NEXT WINDOW LOCATION 
JMP SMDONE 

NEWROW: MOV COLPOS , 1 ; POINT TO STARTING COLUMN OF A NEW ROW 
ADD ROWPOS , 6 ; POINT ROWPOS TO THE NEXT ROW 

SMDONE : RET 


ADDNMOV ENDP 


PROCEDURE : DISPWNDX 
FUNCTION : 

THIS PROCEDURE DISCONNECTS FROM WINDOW MANAGER SERVICES TO 
SHOW THE CHANGES MADE ON THE SCREEN AND TO REMOVE THE WSCTRL 
OIA TO LET THE USER SEE THE NEW MESSAGE ON THE 5TH LINE OF THE 
WORK WINDOW. AFTER WAITING A BIT, THE PROCEDURE RECONNECTS 
TO WINDOW MANAGER SERVICES. 


we Ne se ee Ne Me Se Ne ONO 


DISPWNDX PROC NEAR 


DISCSWSC WSCTRL,QSSESSID 
; DISCONNECT FROM WINDOW SERVICES 
CHEK4ERR DWRETNCD 


ee 


tt Ae Ae Ae ee ee A A A A A A A 
7; WAIT A BIT SO THE USER CAN READ THE MESSAGE ;; 


ee 


yn ae Ae A ee A A ee A 


MOV CxX,12 ; LOAD CX WITH THE NUMBER OF DELAY CYCLES 
DELAY1: PUSH CX ; SAVE THE COUNT 

MOV CX, OFFFFH ; LOAD CX FOR ONE DELAY CYCLE 
DELAY2: LOOP DELAY2 ; BUSY WAIT 

POP CX ; RESTORE THE COUNT 

LOOP DELAY1 ; DELAY FOR ANOTHER DELAY CYCLE 


CONNSWSC WSCTRL,QSSESSID 

; CONNECT TO WINDOW SERVICES 
CHEK4ERR CWRETNCD 
RET 


DISPWNDX ENDP 
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; 
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. 
7 
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7 
av 
7 
f 
r 
° 
7 
; 
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° 
; 
° 
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HECKERR 


ERROR: 
CHECKERR 


MAIN 


CODESEG 


Sample Program 3 


PROCEDURE CHECKERR 
FUNCTION 
CHECK THE RETURN CODES FROM THE API CALLS. BL CONTAINS 

THE RETURN CODE IN THE PARAMETER LIST. BL AND CL ARE CHECKED 

FOR OS. IF EITHER DOES NOT CONTAIN A 0, AN ERROR MESSAGE IS 

DISPLAYED AND THE PROGRAM IS TERMINATED. 

NOTE THIS IS A VERY SIMPLE ERROR HANDLER USED TO PRE- 
SERVE PROGRAM FLOW AND IS NOT LISTED AS AN EXAMPLE OF 
AN APPROPRIATE ERROR HANDLER. THIS ERROR HANDLER SIMPLY 
TERMINATES THE PROGRAM WHEN AN ERROR IS ENCOUNTERED 
LEAVING ANY RESOURCES, SUCH AS FIXED LENGTH QUEUES, 
PRESENTATION SPACES, AND A CONNECTION TO THE WINDOW 
SERVICES, STILL ALLOCATED. A MORE APPROPRIATE ERROR 
HANDLER WOULD DELETE ALL RESOURCES BEFORE TERMINATING. 

PROC NEAR 

CMP CL,0 ; CHECK THE RETURN CODE IN CL 

JNE ERROR 

CMP BL,O ; CHECK THE PARAMETER LIST RETURN CODE 

JNE ERROR 

RET ; RETURN CODES OK. RETURN TO CALLER. 


DISPLAY ERRORMSG 


JMP 


ENDP 


ENDP 


ENDS 


END 


FINISH 


=e 


AN ERROR OCCURRED. DISPLAY THE ERROR 
MESSAGE AND EXIT TO DOS. 
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Chapter 28. Sample Program 4 


PAGE 80,132 


PROGRAM : STEMIR 


FUNCTION : 

THIS PROGRAM GRAPHICALLY DISPLAYS (IN BAR CHART FORM) 
INFORMATION ABOUT A BUSINESS. THERE ARE FIVE CATEGORIES OF 
INFORMATION RELATING TO THIS BUSINESS. 

THE CATEGORIES ARE: 1. GROSS REVENUE 

2. NET REVENUE 

3. NUMBER OF PRODUCTS SOLD 
4. EMPLOYEE OVERTIME 

5. EMPLOYEE ILLNESS 


THE DATA CORRESPONDING TO EACH CATEGORY IS LOCATED IN 
A FILE LOCATED ON A VM HOST SYSTEM. 


A MENU IS DISPLAYED AND THE USER CHOOSES ONE OF THE ABOVE 
CATEGORIES. THIS PROGRAM GETS THE DATA THAT CORRESPONDS TO 
THE USER'S CHOICE FROM THE HOST AND GRAPHS THE DATA IN A BAR 
CHART FORM. THIS CONTINUES UNTIL THE USER HITS THE ESCAPE KEY 
FROM THE MENU. 


DATA IS TRANSFERRED FROM THE HOST USING DESTINATION/ORIGIN 
STRUCTURED FIELDS AND THE MFIC API. 


THIS PROGRAM IS NOT WELL BEHAVED SINCE IT USES GRAPHICS 
AND WRITES DIRECTLY TO THE DISPLAY BUFFER. THE INDSPIF UTILITY 
WAS USED TO CREATE A PIF FILE THAT REFLECTS THIS BEHAVIOR. 


THIS PROGRAM DEMONSTRATES THE FOLLOWING 
API FUNCTIONS: 

NAME RESOLUTION 
QUERY ID 
CONNECT TO KEYBOARD/DISCONNECT FROM KEYBOARD 
DISABLE INPUT/ENABLE INPUT 
CREATE A QUEUE/DELETE AN ENTRY 
DEFINE RECEIVE BUFFER 
CONNECT/DISCONNECT TO HOST SESSION 
READ STRUCTURED FIELD 
WRITE STRUCTURED FIELD 
DEQUEUE 
QUERY BASE WINDOW 
WRITE KEYSTROKE 
GET REQUEST COMPLETION 
QUERY ACTIVE TASK 
TRANSLATE 


NOTE: THIS PROGRAM IS SEPARATED INTO TWO LOAD MODULES. 
THIS MODULE CONTAINS THE MAIN BODY OF THE PROGRAM. THE MAIN 
BODY CALLS PROCEDURES IN BOTH THIS AND THE SECOND MODULE. 


NOTE: DESTINATION/ORIGIN STRUCTURED FIELDS CAN ONLY BE 
USED WHEN THE 3270 PERSONAL COMPUTER HAS BEEN CUSTOMIZED FOR 
DFT COMMUNICATIONS. ALSO, THERE IS A HOST PROGRAM THAT RUNS 
ON VM THAT RETRIEVES THE DATA AND COMMUNICATES WITH THIS 
PERSONAL COMPUTER PROGRAM. 


eT ey ee a  ? a a PT a? 7 YY 7) OY eT TT TT TT TT a | eT ae Ty 
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; DOS FUNCTION CALLS 


DISPSTRG EQU 
NOSECHO EQU 


; BIOS VIDEO FUNCTION CALLS 


SETSMODE EQU 
SETSPALL EQU 
WRITEDOT EQU 


; CONSTANTS 

MSGAVAIL EQU 
UPCASE EQU 
AIDKEY EQU 
ESC EQU 


STAKSIZE EQU 


; THE FOLLOWING CONSTANTS ARE USED 


MEDRESSG EQU 
COL$8025 EQU 
GRY EQU 
COLSAXIS EQU 


; THE FOLLOWING ARE REPLY AND WAIT 


WAITCMPS EQU 
RPLYCMPS EQU 
RPLYCMPQ EQU 
WAITCMPQ EQU 


; THE FOLLOWING CONSTANTS ARE USED 
: AND COMMENTS AROUND THE GRAPH 


LENSDASH EQU 
XSVERTEX EQU 
YSVERTEX EQU 
LENXAXIS EQU 
LENYAXIS EQU 
ENTRYSIZ EQU 


XSCOMNT  EQU 
YSCOMNT  EQU 


XSDASHC EQU 
YSDASHC EQU 
XS$TMSG EQU 
YSTMSG EQU 


XSCMSG EQU 
YSCMSG EQU 
XSHKMSG EQU 
YSHKMSG EQU 


F MACRO NAME 
; PARAMETERS 


28-2 


09H 
7 


0 
Li 
12 


04H 
3 
0 
O1H 


20H 
80H 
40H 
40H 


5 
50 
167 
260 
160 
20 


i aT) 


i at el el eT eT 


PRINTING A STRING 
DOS FUNCTION TO READ A CHARACTER WITH NO 
ECHO 


BIOS VIDEO FUNCTION TO SET THE MODE 
BIOS VIDEO FUNCTION TO SET PALETTE 
BIOS VIDEO FUNCTION TO WRITE A DOT 


COMMUNICATION STATUS, MESSAGE AVAILABLE 
FROM HOST 

UPPERCASE SHIFTSTATE 

AID KEY GENERATES A 12H RETURN CODE FROM 
WRITSKEY 

THE ASCII VALUE FOR THE ESCAPE KEY 

SIZE OF THE STACK 


TO SWITCH TO GRAPHICS MODE AND SET THE COLORS 


“ee Ne Ne Ne 


MEDIUM RESOLUTION IN GRAPHICS MODE 

80 COLUMNS BY 25 ROWS IN ASCII MODE 

THE PALETTE EQUALS GREEN, RED AND YELLOW 
THE COLOR OF THE AXIS IS GREEN 


STATES USED BY SOME OF THE API FUNCTIONS 


we me Ne NO 


WAIT FOR COMPLETION SIGNAL 
REPLY COMPLETION SIGNAL 

REPLY COMPLETION QUEUE 

WAIT FOR ROE ON COMPLETION QUEUE 


TO PRINT THE GRAPH (E.G. BAR CHARTS) 


OT et TT nT i a St St nt el) 


LENGTH OF THE DASH ON THE VERTICAL AXIS 

X COORDINATE FOR THE AXIS VERTEX 

Y COORDINATE FOR THE AXIS VERTEX 

LENGTH OF THE Y AXIS 

LENGTH OF THE X AXIS 

THERE ARE 20 BYTES PER ENTRY IN THE COMMENT 
TABLES 

THE COMMENTS DESCRIBING THE INTERVALS ALONG 
THE X AXIS AT (XS$COMNT,YSCOMNT) 

I.E. COLUMN, ROW 

THE COMMENTS DESCRIBING THE INTERVALS ALONG 
THE Y AXIS BEGIN AT (XS$DASHC,YSDASHC) 

THE MESSAGE THAT DESCRIBES THE TYPE OF DATA 
THAT IS BEING DISPLAYED IS LOCATED AT 
(X$TMSG, YSTMSG) 

THE MESSAGE THAT DISPLAYS THE CORPORATION 
NAME IS LOCATED AT (XS$CMSG,YSCMSG) 

THE MESSAGE THAT DISPLAYS THE "HIT ANY 
KEY..." IS LOCATED AT (XSHKMSG,YSHKMSG) 


*** MACRO DEFINITIONS *** 


DOSFXN 
FXNNUM 


-- DOS FUNCTION NUMBER 


we Ne Ne Me Ne 


DOSFXN 


ey a eT eT eT eT 


MOVSCURS 


et et ee ee et eT et eT 


DISPMENU 


REP 


ue se Se Ne me NO ON 


FUNCTION 


THIS WILL CALL A DOS 
FXNNUM. 


MACRO FXNNUM 


MOV 
INT 


ENDM 


AH, FXNNUM 
21H 


MACRO NAME : MOVSCURS 


FUNCTION 


THIS WILL CALL THE 
CURSOR TO POSITION 


MACRO 
MOV 
MOV 
INT 


ENDM 


AH, 2 
BH,0O 
10H 


MACRO NAME : DISPMENU 
PARAMETERS : SESSMGR 
PARAMETERS : PCSESSID 


FUNCTION 


MENUSPS 


Sample Program 4 


FUNCTION SPECIFIED BY THE PARAMETER 


THE FUNCTION NUMBER BELONGS IN AL 
CALL DOS 


BIOS VIDEO FUNCTION TO MOVE THE 
(X$SCOLUMN ,Y$ROW). 


. 
’ 
° 
‘ 


. 
f 


BIOS VIDEO FUNCTION NUMBER TWO 
THE PAGE NUMBER IS ZERO IN GRAPHICS MODE 
CALL DOS 


RESOLVED VALUE FOR WSCTRL 
SESSION ID FOR WINDOW WITH THE MENU 
SCREEN NUMBER 


THIS WILL MAKE THE MENU APPEAR. 


MACRO 


CLD 
MOV 
MOV 


MOV 
MOV 
MOV 
MOVSB 


MOV 
MOV 


ENDM 


PCSESSID,MENUSPS 


CX, 4000 


. 
r 


° 
’ 


SI,OFFSET MENUSPS 


DI,0 
AX, OBOOOH 
ES , AX 


AX , DATASEG 
ES, AX 


MACRO NAME : DRAWVERT 
PARAMETERS : X 


FUNCTION 


YBEGIN 
LEN 
COLOR 


. 
t 


° 
‘ 


=e 


INCREMENT SI AND DI ON THE REPEAT 
MOVE 4000 BYTES OF CHARACTER-ATTRIBUTE 


THE SOURCE DATA BEGINS AT MENUSPS 
THE DESTINATION IS THE DISPLAY BUFFER 
MOVE THE MENU DATA INTO THE DISPLAY BUFFER 


ASSIGN ES TO BACK TO THE DATASEG 


VALUE ON THE X AXIS, (COLUMN) 
VALUE ON THE Y AXIS, (ROW) 
LENGTH OF THE LINE 

COLOR OF THE LINE 
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Tt a eT 


DRAWVERT 


LP: 


BIOS FUNCTION 


EXIT: 


ey ee) ee ee eS en eT eT eT 


DRAWHORZ 


28-4 


THIS WILL DRAW A VERTICAL LINE. 


THE LINE WILL BE DRAWN 


FROM POINT (X,YBEGIN) TO (X,YBEGIN+LEN). 


MACRO X,YBEGIN,LEN, COLOR 

LOCAL LP,EXIT 

; SAVE THE CURRENT Y VALUE 

MOV AX, YBEGIN 

MOV CURRSY , AX 

; HAVE WE REACHED THE LAST 

MOV BX, LEN ; 

ADD BX , CURRSY ; 

CMP CURRSY , BX 

; YES, WE ARE DONE 

JE EXIT 

; NO, TURN THE PEL ON 

; INITIALIZE REGISTERS FOR 

MOV CX,X ; 

MOV AL,COLOR ; 

MOV AH ,WRITEDOT ; 
NUMBER 

MOV DX, CURRSY ; 

INT 10H ; 

; INCREMENT THE ROW NUMBER 

INC CURRSY 

JMP LP 

NOP 

ENDM 

MACRO NAME : DRAWHORZ 


PARAMETERS : Y 
XBEGIN 
LEN 
COLOR 
FUNCTION 


PEL YET? 
THE LAST PEL = THE FIRST PEL PLUS 
THE LENGTH OF THE LINE 


THE BIOS WRITE DOT FUNCTION 
COLUMN NUMBER FOR VERTICAL LINE 
COLOR FOR VERTICAL 


ROW NUMBER OF PEL 
CALL THE BIOS VIDEO FUNCTION 


AND CHECK THE PEL 


-- VALUE ON THE Y AXIS, (ROW) 

-- VALUE ON THE X AXIS, (COLUMN) 
~- LENGTH OF THE LINE 

-- COLOR OF THE LINE 


THIS WILL DRAW A HORIZONTAL LINE. THE LINE WILL BE 


DRAWN FROM POINT 


(XBEGIN,Y) TO POINT (XBEGIN+LEN,Y). 


MACRO Y,XBEGIN,LEN,COLOR 
LOCAL LP,EXIT 

; SAVE THE CURRENT X VALUE 
MOV AX , XBEGIN 

MOV CURRSX , AX 


LP: 


EXIT: 


A eT nl St i eT ee eT eT eT TY 


DRAWAXIS 


Se et et a ee eT ST St MT Ml | 
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; HAVE WE REACHED THE LAST PEL YET? 


MOV BX, LEN ; THE LAST PEL = THE FIRST PEL PLUS 
ADD BX ,CURRSX : THE LENGTH OF THE LINE 
CMP CURRSX,BX 


; YES, WE ARE DONE 
JE EXIT 


; NO, TURN THE PEL ON 
; INITIALIZE REGISTERS FOR THE BIOS WRITE DOT FUNCTION 


MOV DX, Y ; ROW NUMBER FOR VERTICAL LINE 
MOV AL ,COLOR ; COLOR FOR VERTICAL 

MOV AH ,WRITEDOT ; BIOS FUNCTION NUMBER 

MOV CX ,CURRS$X ; ROW NUMBER OF PEL 

INT 10H ; CALL THE BIOS VIDEO FUNCTION 
; INCREMENT THE COLUMN NUMBER AND CHECK THE PEL 

INC CURR$X 

JMP LP 

NOP 

ENDM 


MACRO NAME : DRAWAXIS 

PARAMETERS : XSVERTEX-- X COORDINATE OF THE AXIS VERTEX 
YSVERTEX-- Y COORDINATE OF THE AXIS VERTEX 
LENXAXIS-- LENGTH OF THE X AXIS 
LENYAXIS-- LENGTH OF THE Y AXIS 

FUNCTION 

THIS WILL DRAW THE VERTICAL AND HORIZONTAL AXIS FOR THE 
BAR CHARTS. 


MACRO XS$VERTEX,Y$VERTEX , LENXAXIS, LENYAXIS 


; THE BEGINNING POINT OF THE VERTICAL AXIS = (YSVERTEX - LENYAXIS) 
MOV AX, YSVERTEX 
SUB AX, LENYAXIS 


; DRAW THE VERTICAL LINE 
DRAWVERT XSVERTEX,AX,LENYAXIS,COLSAXIS 


; DRAW THE HORIZONTAL LINE 
DRAWHORZ YSVERTEX ,X$VERTEX , LENXAXIS , COLSAXIS 


ENDM 


MACRO NAME : CMNTSDSH 
PARAMETERS : FIRSTINP-- THE USERS FIRST INPUT, WHICH DATA 
THE USER WANTED TO DISPLAY 
INTVTABL-- THE TABLE NAME OF THE COMMENTS FOR 
THE Y AXIS 
FUNCTION 
THIS WILL DISPLAY THE COMMENTS ALONG SIDE THE DASHES ON 
THE Y AXIS. 


Chapter 28. Sample Program 4 28-5 


Sample Program 4 


CMNTSDSH MACRO FIRSTINP, INTVTABL 
LOCAL NXTCMNT 
; CONVERT THE USERS FIRST INPUT FROM ASCII TO BINARY 
MOV BL,FIRSTINP 
XOR BH, BH 
SUB Bx," 0" 
; FIND THE BEGINNING OF THE ENTRY THAT CORRESPONDS TO THE USERS CHOICE 
SUB BX,1 ; THE TABLES BEGIN AT OFFSET ZERO 
MOV AL, ENTRYSIZ 
MUL BL 
MOV SI,AX 
; FOR EACH DASH 
MOV CxX7o ; INITIALIZE THE LOOP COUNTER 
MOV DL,X$DASHC ; THE FIRST COMMENTS STARTS HERE 
MOV DH, YSDASHC . AT (XSDASHC,YSDASHC) 


; MOV THE CURSOR TO THE CORRECT POSITION 
NXTCMNT: MOVSCURS 


PUSH DX ; SAVE THE CURRENT POSITION OF THE CURSOR 
; CALCULATE THE POSITION IN THE TABLE OF THE COMMENT TO BE PRINTED 
MOV DX,OFFSET INTVTABL 

ADD DX,SI 


; PRINT THE STRING 
DOSFXN DISPSTRG 


; INCREMENT THE INDEX INTO THE TABLE 


ADD SI,4 

; INCREMENT THE POSITION OF THE NEXT DASH 

POP DX 

SUB DH,4 

LOOP NXTCMNT ; CONTINUE PROCESSING 
ENDM 


MACRO NAME : CMNTSGRP 
PARAMETERS : FIRSTINP-- THE USERS FIRST INPUT, WHICH DATA 
THE USER WANTED TO DISPLAY 
SECNDINP-- THE USERS SECOND INPUT, WHETHER THE 
DATA IS DISPLAYED BY YEARS OR MONTHS 
FUNCTION 
THIS WILL DISPLAY THE COMMENTS ON THE X AND Y AXIS. 


St ee i eT Se eT Mt MT) 


CMNTSGRP MACRO FIRSTINP , SECNDINP 


; PUT FIVE HORIZONTAL DASHES ON THE VERTICAL AXIS 


MOV AX ,XSVERTEX ; BEGINNING OF A DASH = COLUMN~LENGTH 
SUB AX , LENSDASH ; OF A DASH 

MOV DASHSBEG , AX ; STORE THE VALUE 

MOV AX,LENYAXIS ; FIGURE OUT THE NUMBER OF ROWS BETWEEN 
DIV FIVE ; DASHES = LENYAXIS / 5 

MOV AH,O 

MOV DASHINTV, AX ; STORE THE INTERVAL BETWEEN DASHES 
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; CALCULATE THE FIRST DASH ROW 


MOV CURRSY,YSVERTEX ; THE Y VERTEX 
SUB CURRSY,LENYAXIS ; MINUS THE LENGTH OF THE Y AXIS 
; FOR EACH FIVE DASHES DRAW A HORIZONTAL LINE 
MOV CXx,5 
DRAWDASH: MOV SAVECX , CX ; SAVE THE LOOP COUNTER 
DRAWHORZ CURRSY,DASHSBEG,LENSDASH , COLSAXIS 
MOV AX , DASHINTV ; UPDATE THE ROW VALUE 
ADD CURRSY , AX 
; GET THE LOOP COUNTER 
MOV CX , SAVECX 
LOOP DRAWDASH 
; MOVE THE CURSOR TO PRINT THE COMMENT UNDER THE X AXIS 
MOV DL,X$COMNT ; COLUMN 
MOV DH, YSCOMNT ; ROW 
MOVSCURS 
; FIND OUT WHICH INTERVAL WE ARE WORKING WITH 
CMP SECNDINP,'Y' 
JE PRINTYRS 


; PRINT MONTHS 
MOV DX,OFFSET MONTHS 
DOSFXN  DISPSTRG 


; PRINT THE COMMENTS BY THE DASHES ON THE Y AXIS 
CMNTSDSH FIRSTINP,MSINTVL 
JMP NXTCMNT 


; PRINT YEARS 
PRINTYRS: MOV DX,OFFSET YEARS 
DOSFXN DISPSTRG 


; PRINT THE COMMENTS BY THE DASHES ON THE Y AXIS 
CMNTSDSH FIRSTINP,YSINTVL 


; MOVE THE CURSOR IN ORDER TO 
PRINT A MESSAGE THAT DESCRIBES THE TYPE OF DATA BEING DISPLAYED 


° 
’ 


NXTCMNT: MOV DL,X$TMSG 
MOV DH, Y$TMSG 
MOVSCURS 
; CALCULATE THE ADDRESS OF THE APPROPRIATE MESSAGE TO PRINT UNDER 
; THE AXIS | 
MOV AL, FIRSTINP ; CONVERT THE USERS FIRST INPUT FROM ASCII 
SUB AL, ' 1! ; TO HEXADECIMAL 
MUL LENCMNT ; THE OFFSET INTO THE TABLE IS THE USERS 

; CHOICE * THE LENGTH OF A MESSAGE 

MOV DX,OFFSET DATATTAB 
ADD DX , AX ; ADD THE OFFSET TO THE BEGINNING OF THE 


; TABLE 


; PRINT THE MESSAGE 


DOSFXN DISPSTRG 

; MOVE THE CURSOR IN ORDER TO PRINT "HIT ANY KEY TO RETURN TO MENU" 
MOV DL,XSHKMSG 

MOV DH, YSHKMSG 

MOVSCURS 
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; PRINT THE MESSAGE UNDER THE GRAPH 
MOV DX,OFFSET HITKEYM 
DOSFXN DISPSTRG 


; MOVE THE CURSOR IN ORDER TO PRINT THE CORPORATION NAME 


MOV DL ,XSCMSG 
MOV DH, YSCMSG 
MOVSCURS 


; PRINT THE CORPORATION NAME UNDER THE GRAPH 
MOV DX,OFFSET CORPNAME 
DOSFXN DISPSTRG 


ENDM 


MACRO NAME : DISPDATA 
PARAMETERS : FIRSTINP-- THE USER'S CHOICE 
SECNDINP-- INTERVAL OF DATA (MONTH OR YEAR 
FUNCTION 
THIS WILL DISPLAY DATA ON A GRAPHICS SCREEN IN A BAR 
CHART FORM. 


bt at aT Tt eT eT eT YT) 


DISPDATA MACRO FIRSTINP,SECNDINP 


; SET THIS WINDOW TO GRAPHICS MODE 


DISPD: MOV AL ,MEDRESSG ; MEDIUM RESOLUTION GRAPHICS 
MOV AH ,SETSMODE ; BIOS FUNCTION TO SET THE MODE 
INT 10H 
; SET THE COLOR PALETTE 
MOV BH,COLSAXIS 
MOV BL,GRY 
MOV AH, SETSPALL 
INT 10H 


; DRAW THE AXIS FOR THE BAR CHARTS 
DRAWAXIS XS$SVERTEX, YSVERTEX , LENXAXIS,LENYAXIS 


; DRAW BARS ON THE BAR CHART 
CALL GRAFDATA 


; COMMENT THE GRAPH 
CMNTSGRP FIRSTINP,SECNDINP 


; WAIT FOR THE USER TO HIT A KEY 


DOSFXN NOSECHO ; DOS FUNCTION TO INPUT A CHARACTER WITHOUT 
| ; ECHOING IT 

;SET THE WINDOW BACK TO ASCII MODE 

MOV AL,COL$8025 

MOV AH, SETSMODE 

INT 10H 

ENDM 
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MACRO NAME : GETDATA 


PARAMETERS : MFIC -- RESOLVED VALUE FOR MFIC 
KEYBOARD-- RESOLVED VALUE FOR KEYBOARD 
HOSTSID -- SESSION ID FOR THE HOST 
PCTSKID ->= PC TASK ID 
STRTPROG-- THE SCAN CODES TO START THE HOST 
PROGRAM. 
SENDACK -- THE NAME OF THE BUFFER SENT TO THE 


HOST TO ACKNOWLEDGE THE FACT THAT 
WE RECEIVED THE DATA FROM THE HOST 
BUFFER -- MEMORY LOCATION OF RECEIVE BUFFER 
FUNCTION 
THIS WILL GET DATA FROM THE HOST. 


=e Ne Ne Me Ne Ne we HH NO 8 Me Me Ne RN Of 


GETDATA MACRO MFIC,KEYBOARD,HOSTSID,PCTSKID,STRTPROG, SENDACK, BUFFER 


; CONNECT TO MFIC, CONNECT TO THE HOST KEYBOARD, 
; DISABLE INPUT TO THE HOST AND CREATE A FIXED LENGTH QUEUE 
CALL CONNHOST 


; PRINT A MESSAGE THAT SAYS WE ARE GETTING DATA FROM THE HOST 
CALL GETDATAM 


; DEFINE A BUFFER TO RECEIVE INPUT FROM THE HOST 

; THIS BUFFER IS DEFINED BEFORE THE HOST APPLICATION IS STARTED 
; IN ORDER TO HAVE A BUFFER READY FOR THE HOST'S DATA. 

DEFSRBUF WAITCMPQ,MFIC,HOSTSID,PCTSKID,BUFFER 

GETSCOMP 40H 

CHEK4ERR 19,DBRETNCD 


; START UP THE HOST APPLICATION, I.E. SEND THE KEYSTROKES TO THE 

; HOST TO INVOKE A PROGRAM NAMED EXAMP 

MOV AL, IN1SCNCD THE USERS SELECTION FROM THE MENU IS USED 
MOV RECNUM , AL AS A RECORD NUMBER. THE HOST WILL SEND 

A RECORD OF INFORMATION FROM A DATA FILE 
; ON THE HOST. 

WRITSKEY KEYBOARD,HOSTSID,,,STRTPROG 


eo =e Se Ne 


CMP WKPARLST.WKRETNCD , AIDKEY 
; IF THE LAST KEY WAS SENT THEN AN AID 
JNE PRNTER ; KEY WAS GENERATED (RETURN CODE = 12) 
MOV WKPARLST.WKRETNCD, 0 
PRNTER: CHEK4ERR 20,WKPARLST.WKRETNCD 


; OTHERWISE CHECK FOR ANOTHER KEY 


; GET THE COMMUNICATION STATUS FROM THE FIXED LENGTH QUEUE 
GTSTATUS: DEQUEUE 02H,SFS$QSID 
CHEK4ERR 21 


; IF THERE IS COMMUNICATION STATUS AND THERE IS NOT 
; A MESSAGE AVAILABLE FROM THE HOST THEN CLEAN UP AND EXIT THIS 
H ROUTINE BECAUSE THERE IS A PROBLEM WITH THE HOST 


CMP DQOSTATUS ,MSGAVAIL 
JE READMSG 
JMP PERRMSG 


; THERE IS A MESSAGE FROM THE HOST SO READ IT INTO OUR BUFFER 
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READMSG: READSSF 40H,40H,MFIC,HOSTSID,PCTSKID 
GETSCOMP 40H 
CHEK4ERR 22,RSRETNCD 


; TELL THE HOST THAT WE RECEIVED THE INFORMATION 
WRITSSF RPLYCMPS ,WAITCMPS ,MFIC,HOSTSID,PCTSKID,SENDACK 
CHEK4ERR 23,WSRETNCD 


JMP CLNUP 
; PRINT AN ERROR MESSAGE 

PERRMSG: MOV DX,OFFSET HOSTPROB 
MOV CX, DQSTATUS 


CHEK4ERR 21 
DOSFXN DISPSTRG 


; DELETE THE FIXED LENGTH QUEUES, ENABLE INPUT TO THE HOST AND 
; DISCONNECT FROM THE HOST 
CLNUP : CALL DISCHOST 


ENDM 


; 3270 P.C. API MACROS 


MACRO : CHEK4ERR 
FUNCTION : 
SET UP THE REGISTERS FOR THE ERROR CHECKER PROCEDURE. 


A et ee ee et TY 


CHEK4ERR MACRO CODE,RETNCODE 
MOV AL , CODE 
IFNB <RETNCODE> IF THERE IS A PARAMETER LIST RETURN CODE 


MOV BL, RETNCODE ; SPECIFIED, PASS THE RETURN CODE AND THE 
MOV BH, RETNCODE+1 7 FUNCTION ID TO THE ERROR CHECKER IN BX 


ELSE OTHERWISE, SEND A O IN BL 
MOV BL,O 

ENDIF 

CALL CHECKERR ; CALL THE ERROR CHECKER 
ENDM 


MACRO NAME : DEFSRBUF 


PARAMETERS : WAITTYPE -~ WAIT TYPE(40H=WAIT FOR COMPLETION 
OOH=DO NOT WAIT 
MFIC -~- RESOLVED VALUE FOR MFIC 
HOSTID -- HOST SESSION ID 
PCTSKID -- PC TASK ID 
BUFFER ~- MEMORY LOCATION NAME OF THE MESSAGE 
BUFFER 
FUNCTION : 


USE THIS SERVICE TO DEFINE A BUFFER THAT WILL BE USED 
TO RECEIVE A MESSAGE FROM THE SPECIFIED HOST SESSION. 
THIS SERVICE IS VALID FOR DFT HOST SESSIONS ONLY. 


ST i et et eS et eT en eT | eT ee eT! a TT 
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DEFSRBUF MACRO WAITTYP,MFIC,HOSTID,PCTSKID,BUFFER 


; INITIALIZE PARAMETER LIST FOR DEFSRBUF 

MOV DBRETNCD , OOH DBRETNCD MUST BE O BEFORE REQUEST 
MOV DBFXNID,OOH DBFXNID MUST BE O BEFORE REQUEST 
MOV AL,HOSTID HOST ID IN 

MOV DBHOSTID,AL THE LIST 

MOV AX, PCTSKID PC TASK ID 

MOV DBTASKID , AX IN THE LIST 

MOV AX,OFFSET BUFFER OFFSET OF MESSAGE BUFFER 

MOV DBOFFSET , AX IN THE LIST 

MOV AX,SEG BUFFER SEGMENT OF THE MESSAGE BUFFER 
MOV DBSEGMNT , AX IN THE LIST 


se Se Se Ne Ne Ne Ne Ne Me Ne 


; INITIALIZE THE 8 BYTE HEADER OF THE MESSAGE BUFFER 

MOV BUFFER,0O 

MOV WORD PTR BUFFER + 2,0 

MOV WORD PTR BUFFER + 4,800H ;LENGTH OF RECEIVE BUFFER 
MOV WORD PTR BUFFER + 6,0 


; INITIALIZE REGISTERS FOR DEFSRBUF 
MOV AH,O9H 
MOV AL,O5H 
MOV  BH,40H 
MOV BL,WAITTYP ; WAIT TYPE IN BL 

MOV CX,0 ; PRIORITY IN CX 

MOV DX,MFIC ; RESOLVED VALUE FOR MFIC 

MOV DI, SEG DBRETNCD ; SEGMENT ADDRESS OF PARAMETER LIST 
MOV ES,DI ; IN ES 

MOV DI,OFFSET DBRETNCD ; OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR DEFSRBUF SERVICE 
INT 7AH 


ENDM 


MACRO : WRITSKEY 


PARAMETERS : SERVTYPE -- SERVICE TYPE 
SESSID -- SESSION ID 
SCANCD -- SCAN CODE 
SHIFST -- SHIFT STATE 
LISTNAME -- THE NAME OF THE LIST OF KEYSTROKES 
TASKID -- CONNECTOR'S TASK ID (OPTIONAL) 
FUNCTION 


SEND A KEYSTROKE OR A LIST OF KEYSTROKES TO THE 
SPECIFIED SESSION. 


ee) eT eT ee. eT eT eT TY 


WRITSKEY MACRO SERVTYPE,SESSID,SCANCD,SHIFST,LISTNAME , TASKID 
LOCAL WKEND 


MOV WKPARLST.WKRETNCD , OH 

WKRETCD MUST BE O FOR THE CALL 
WKFXNID MUST BE O FOR THE CALL 
PUT THE SESSION ID IN PARM LIST 


MOV WKPARLST.WKFXNID,0OH 
MOV AL,SESSID 
MOV WKPARLST.WKSESSID,AL 


=e Oe Ne 


Chapter 28. Sample Program4 28-11 


Sample Program 4 


WKEND: 


Ct eS ee eT et eT eT 
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IFNB <SCANCD> ; CHECK IF SENDING ONE KEYSTROKE 
; OR A LIST OF KEYSTROKES 


; SENDING ONE KEYSTROKE 


MOV AL,SCANCD ; PUT THE SCAN CODE IN THE PARM LIST 
MOV WKPARLST.WKSCNCOD,AL 

MOV AL,SHIFST ; PUT SHIFT STATE IN THE PARM LIST 
MOV WKPARLST.WKSHFST,AL 

MOV AL,20H ; PUT THE OPTION BYTE FOR SENDING 
MOV WKPARLST.WKOPTION,AL ; ONE CHARACTER IN THE PARM LIST 
ELSE 


; SENDING A LIST OF KEYSTROKES 


MOV AX,OFFSET LISTNAME ; PUT THE OFFSET ADDRESS OF THE LIST 
MOV WKPARLST.WKLSTOFF ,AX 
: INTO THE PARAMETER LIST 
MOV AX,SEG LISTNAME ; PUT THE SEGMENT ADDRESS OF THE LIST 
MOV WKPARLST.WKLSTSEG ,AX; INTO THE PARAMETER LIST 


MOV AL,30H ; PUT THE OPTION BYTE FOR SENDING A 
MOV WKPARLST.WKOPTION,AL 
; LIST OF CHARS. IN THE PARM LIST 


ENDIF 

IFNB <TASKID> ; IF A CONNECTOR'S TASK ID WAS 
MOV AX,TASKID ; SPECIFIED, PUT IT IN THE LIST 
ELSE 

MOV AX,0 ; OTHERWISE PUT A O IN THE LIST 
ENDIF 


MOV WKPARLST.WKTASKID,AX 


; INITIALIZE THE REGISTERS FOR WRITSKEY 

MOV AH,O9H 

MOV AL,O4H 

MOV BH,80H 

MOV BL,20H 

MOV CX,O000H 

MOV DX,SERVTYPE ; SERVICE TYPE IN Dx 

MOV DI, SEG WKPARLST ; GET SEGMENT ADDRESS OF PARM LIST 


MOV ES,DI AND PUT IT IN ES 

MOV DI, OFFSET WKPARLST SET DI TO OFFSET OF PARM LIST 
INT 7AH ; PASS THE REQUEST TO THE API 
NOP 

ENDM 


MACRO NAME : DEQUEUE 
PARAMETERS : WAITTYPE -- WAIT TYPE 
QUEUEID -- ID OF THE FIXED-LENGTH QUEUE 
FUNCTION 
OBTAIN AN ELEMENT FROM A FIXED-LENGTH QUEUE. 
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DEQUEUE MACRO WAITTYPE,QUEUEID 


; INITIALIZE REGISTERS FOR DEQUEUE 
MOV AH,13H 

MOV BL,WAITTYPE 
MOV CX,0004H 
MOV DX,QUEUEID ; FIXED-LENGTH QUEUE ID IN DX 

MOV DI, SEG DQSESSID ; SEGMENT ADDRESS OF DATA AREA IN ES 
MOV ES,DI 

MOV DI,OFFSET DQSESSID ; OFFSET ADDRESS OF DATA AREA IN DI 


WAIT TYPE IN BL 


~e 


; SIGNAL WORKSTATION PROGRAM FOR DEQUEUE SERVICE 
INT 7AH 


ENDM 


MACRO NAME : READSSF 


; PARAMETERS : RPLYTYPE -- REPLY TYPE 

; WAITTYPE -- WAIT TYPE 

; MFIC -- RESOLVED VALUE FOR MFIC 

; HOSTID -- HOST SESSION ID 

7 PCTSKID -=- PC TASK ID 

i FUNCTION 

; USE THIS SERVICE TO READ STRUCTURED FIELD DATA FROM THE 
; SPECIFIED HOST SESSION. THIS SERVICE IS VALID FOR DFT 
; HOST SESSIONS ONLY. 

READSSF MACRO RPLYTYPE,WAITTYP ,MFIC,HOSTID,PCTSKID 


LOCAL RSEND 


; INITIALIZE PARAMETER LIST FOR READSSF 
MOV RSRETNCD , OOH RSRETNCD MUST BE O BEFORE REQUEST 
MOV RSFXNID,0OOH RSFXNID MUST BE O BEFORE REQUEST 


MOV AL ,HOSTID HOST ID IN 
MOV RSHOSTID,AL THE LIST 
MOV AX, PCTSKID PC TASK ID 
MOV RSTASKID,AX IN LIST 


=e “se ™O Ne UN Ue ONO 


MOV  RSZERO,O THIS FIELD MUST BE ZEROED 
; INITIALIZE REGISTERS FOR READSSF 

MOV AH,O9H 

MOV AL,03H 

MOV BH,RPLYTYPE 
MOV BL,WAITTYP 


REPLY TYPE IN BH 
WAIT TYPE IN BL 


MOV CX ,0 ; PRIORITY IN CX 
MOV DX,MFIC ; RESOLVED VALUE FOR MFIC 
MOV DI, SEG RSRETNCD ; SEGMENT ADDRESS OF PARAMETER LIST 
MOV ES,DI ; IN ES 
ca 


MOV DI,OFFSET RSRETNCD OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR READSSF SERVICE 
INT 7AH 


ENDM 
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MACRO NAME : WRITSSF 


PARAMETERS : RPLYTYPE -- REPLY TYPE 
WAITTYPE -- WAIT TYPE 
MFIC -- RESOLVED VALUE FOR MFIC 
HOSTID -- HOST SESSION ID 
PCTSKID -- PC TASK ID 


STRSDATA -- MEMORY LOCATION NAME OF STRUCTURED 
FIELD DATA 
FUNCTION : 
USE THIS SERVICE TO WRITE STRUCTURED FIELD DATA FROM THE 
SPECIFIED HOST SESSION. THIS SERVICE IS VALID FOR DFT 
HOST SESSIONS ONLY. 


a et et eT ee eT ee et TY 


WRITSSF MACRO RPLYTYPE,WAITTYP,MFIC,HOSTID,PCTSKID,STRSDATA 


; INITIALIZE PARAMETER LIST FOR READSSF 
MOV WSRETNCD , OOH ; WSRETNCD MUST BE O BEFORE REQUEST 
MOV WSFXNID, OOH ; WSFXNID MUST BE O BEFORE REQUEST 
MOV AL,HOSTID ; HOST ID IN 
MOV WSHOSTID,AL ; THE LIST 

; OFFSET AND SEGMENT OF DATA IN LIST 
MOV WSOFFSD,OFFSET STRSDATA 
MOV WSSEGTD,SEG STRSDATA 


MOV AX ,PCTSKID ; PC TASK ID 
MOV WSTASKID,AX : IN LIST 
MOV WSZERO,0 ; THIS FIELD MUST BE ZEROED 


; INITIALIZE THE FIELDS IN THE STRUCTURED FIELD 8 BYTE HEADER 
MOV STRSDATA,O - 

MOV WORD PTR STRSDATA + 4,0 

MOV WORD PTR STRSDATA + 6,0 


; INITIALIZE REGISTERS FOR WRITSSF 
MOV AH, 09H 
MOV AL,O4H 
MOV BH,RPLYTYPE 
MOV BL,WAITTYP 


REPLY TYPE IN BH 
WAIT TYPE IN BL 


MOV CxX,0 PRIORITY IN Cx 
MOV DI, SEG WSRETNCD SEGMENT ADDRESS OF PARAMETER LIST 
MOV ES ,DI IN ES 


MOV DX,MFIC ; RESOLVED VALUE FOR MFIC 
; 


MOV DI,OFFSET WSRETNCD OFFSET OF PARAMETER LIST IN DI 
; SIGNAL WORKSTATION PROGRAM FOR WRITSSF SERVICE 
INT 7AH 


ENDM 


MACRO : GETSCOMP 
FUNCTION: 

USE THIS SERVICE TO OBTAIN THE CONTENTS OF A SPECIFIED 
REQUEST QUEUE ELEMENT. . 
ONE PARAMETER IS PASSED WHICH INDICATES WHETHER THE USER 
WANTS TO WAIT UNTIL RESULTS ARE READY (40H) OR TO CHECK IF 
RESULTS ARE AVAILABLE AND GET THEM IF THEY ARE READY (OOH). 


bk i, i i EL nt i nl nt a | 
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GETSCOMP MACRO WAIT 


MOV BL,WAIT 


MOV AH,83H ; SET UP THE REGS FOR A GETSCOMP CALL 
MOV CxX,O0O00H 

INT 7AH 

ENDM 


STACKSEG SEGMENT STACK 'STACK' 
DB STAKSIZE DUP(?) 
STACKSEG ENDS 


DATASEG SEGMENT PUBLIC 


; THESE VARIABLES ARE LOCATED IN THE SECOND LOAD MODULE 


EXTRN PCSESSID: BYTE, KEYBOARD: WORD ,MENUSPS: BYTE,HOSTSID: BYTE, PCTASKID: WORD 

EXTRN MFIC:WORD, IN1ISCNCD: BYTE, SF$Q$ID:WORD,SECNDINP: BYTE, SESSMGR: WORD 

EXTRN FIRSTINP: BYTE 

; THESE VARIABLES ARE USED BY THE SECOND LOAD MODULE 

PUBLIC BUFFAREA ,CURRSY 

CURRSY DW O CURRENT Y POINTER, USED TO DRAW A 
VERTICAL LINE 

CURRSX DW O CURRENT X POINTER, USED TO DRAW A 


HORIZONTAL LINE 
USED TO DRAW A DASH ON THE Y AXIS 
INTERVAL BETWEEN DASHED ON THE Y AXIS 


DASHSBEG DW O 
DASHINTV DW O 
' 


me Ae Me Me Me Ne 


MONTHS DB 'J F MA M JJ A SO N_ DS! 

YEARS DB 1980 1981 1982: 1983 1984s' 
; COMMENTS TO BE DISPLAYED UNDER THE X AXIS 
; OF THE GRAPH 

SAVECX DW O ; SAVE A LOOP COUNTER 

FIVE DB 5 ; USED FOR DIVIDE INSTRUCTION 


TABLES FOR PRINTING OUT COMMENTS BY THE Y AXIS 
THE FIRST TABLE IS FOR PRINTING OUT DATA BY THE MONTH 
THE SECOND TABLE IS FOR PRINTING OUT DATA BY THE YEAR 
MSINTVL DB ' 20S 40$ 60$ 80$100$' 


wa "ee NO 


DB ' 8S 16S 24S 32S 40$' 
DB ' 3S 6S 9$ 13S 15$! 
DB ' 20$ 40S 60S 80$100S! 
DB: + 5S 20S 15S: 208-255" 
YSINTVL DB '180$360$540$720$900S! 
DB ' 80$160$240$320$400S'! 
DB ' 30$ 60S 90$130$150$! 
DB ' 60$120$180$240$300S$'! 
DB ' 25S 50$ 75$100$125S'! 
; MESSAGES 
HOSTPROB DB "PROBLEM WITH HOST, CANNOT GET DATA $' 
CORPNAME DB 'STEMIR CORPORATIONS! 
WAITMSG DB 'GETTING DATA FROM THE HOSTS' 
HITKEYM DB "HIT ANY KEY TO RETURN TO MENUS' 
; MESSAGES PRINTED UNDER THE GRAPH DESCRIBING THE DATA 
DATATTAB DB ‘GROSS REVENUE (THOUSANDS) S$ ; 
DB 'NET REVENUE (THOUSANDS) $ : 
DB "PRODUCTS SOLD (THOUSANDS) S$ t 
DB "EMPLOYEE OVERTIME (HOURS)S ; 
DB ‘EMPLOYEE ILLNESS (DAYS) §$ : 
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; LENGTH OF EACH STRING IN THE ABOVE TABLE 
LENCMNT DB 33 


A LIST OF SCAN CODES AND SHIFTSTATES SENT TO THE HOST TO START THE 
PROGRAM THAT IS ON THE HOST 


STRTPROG DW 54 ; LENGTH OF THE LIST 

E DB 24H ,UPCASE 

x DB 22H, UPCASE 

A DB 1CH ,UPCASE 

M DB 3AH , UPCASE 

P DB ADH , UPCASE 

SPACE1 DB 29H, UPCASE 

Ss DB 1BH, UPCASE 

T DB 2CH ,UPCASE 

ES$2 DB 24H , UPCASE 

MS2 DB 3AH,UPCASE 

I DB 43H, UPCASE 

R DB 2DH , UPCASE 

SPACE2 DB 29H, UPCASE 

D DB 23H, UPCASE 

AS2 DB 1CH ,UPCASE 

TS$2 DB 2CH, UPCASE 

AS3 DB 1CH, UPCASE 

SPACE3 DB 29H, UPCASE 

LFTPARN1 DB 46H, UPCASE 

RS2 DB 2DH , UPCASE 

ES$3 DB 24H, UPCASE 

C DB 21H,UPCASE 

LFTPARN2 DB 46H, UPCASE 

RECNUM DB ? ; THIS IS THE RECORD THAT WE WANT FROM 

; THE HOST 

DB 0 

RHTPARN1 DB 45H ,UPCASE 

RHTPARN DB 45H, UPCASE 

ENTERKEY DB 58H,0 


; 8 BYTE HEADER FOLLOWED BY ACKNOWLEDGMENT THAT IS SENT TO THE HOST PROGRAM 
; VIA WRITSSF 

; THE FORMAT OF THE SUCCESSFUL TRANSMISSION RESPONSE CAN BE FOUND IN 

; APPENDIX B, "FORMAT OF THE HOST INSERT AND INSERT 

; DATA REQUESTS." 
S 


ENDACK DB 0,0,0BH,0,0,0,0,0 
DB 0,0BH,ODOH,47H,05H,63H,06H 
DATBLK DB O70 05 1 


; DEFINE A RECEIVE BUFFER 
; THE RECEIVE BUFFER IS AN EIGHT BYTE HEADER FOLLOWED BY THE DATA AREA 
; THE FORMAT OF THE HOST DATA IS DOCUMENTED IN APPENDIX B, 

"FORMAT OF THE HOST INSERT AND INSERT DATA REQUESTS." 


BUFFER DW 0 
OBLEN DW 0 ; OUTBOUND TRANSMISSION LEN 
; EXCLUDING THE BUFFER HEADER 
RBSSIZ DW 0 ; SIZE OF RECEIVE BUFFER ON DEFSRBUF 
DB 12 DUP(0O) 
DW 0 ; OUTBOUND TRANSMISSION LEN 
; INCLUDING THE BUFFER HEADER 
DB 6 DUP(0) 
LD DW 0 ; LENGTH OF DATA + 5 
BUFFAREA DB 2000 DUP(0) ; 2000 BYTES FOR THE BUFFER 
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; PARAMETER LIST FOR DEFSRBUF 


DBRETNCD 
DBFXNID 
DBHOSTID 


DBOFFSET 
DBSEGMNT 


DBTASKID 


0 
0 
0 
0 
0 
O0001H 
DW O 
6) 
0 
0 
0 
0 
2) 


DUP (0) 


=e se Ne Ne Ne 


, 


. 
, 


Sample Program 4 


RETURN CODE 
FUNCTION NUMBER 
HOST SESSION ID 
UNCHANGED 

NOT USED 


UNUSED 
SEGMENT AND OFFSET OF THE MESSAGE BUFFER 


UNUSED 
PC TASK ID 


SYSTEM WORK AREA 


; PARAMETER LIST STRUCTURE FOR WRITSKEY 


WRKYPARM 
WKRETNCD 
WKFXNID 

WKSESSID 
WKSPARE 

WKTASKID 
WKOPTION 
WKNUMKEY 
WKSCNCOD 
WKSHFST 

WKRESRV2 
WRKYPARM 


WRKYPAR2 
WKLSTOFF 


WKLSTSEG 
WRKYPAR2 


STRUC 
DB 
DB 
DB 
DB 
DW 
DB 
DB 
DB 
DB 
DW 
ENDS 


OO0O0000000 


STRUC 


DB 8 DUP(0O0) 


DW O 
DW 0 
ENDS 


; ALLOCATE STORAGE FOR THE WRITE KEYSTROKE PARAMETER LIST 


WKPARLST 


; DATA AREA FOR DEQUEUE 


DQSESSID 
DORESERV 
DOSTATUS 


; PARAMETER LIST FOR READSSF 


RSRETNCD 
RSFXNID 
RSHOSTID 
RSZERO 


RSOFFSD 
RSSEGTD 


RSTASKID 


WRKYPARM <> 


DB O 
DB O 
DW O 


DB 
DB 
DB 
DB 
DW 
DW 
DW 
DW 
DW 
DW 
DW 
DW 
DW 


O01H 


oOndod000000000 


a L | 


ST a) et a eT eT eT eT eT eT 


SESSION ID 

RESERVED 

STATUS CODE FOLLOWED BY 
STATUS TYPE 


RETURN CODE 

FUNCTION NUMBER 

HOST SESSION ID 

UNCHANGED 

NOT USED 

STRUCTURED FIELD TYPE, (DEST/ORIG) 
UNUSED 

OFFSET ADDRESS OF STRUCTURED FIELD DATA 
SEGMENT ADDRESS OF STRUCTURED FIELD DATA 
UNUSED 

PC TASK ID 


SYSTEM WORK AREA 
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; PARAMETER LIST FOR WRITSSF 
WSRETNCD DB 

WSFXNID DB 

WSHOSTID DB 


RETURN CODE 
FUNCTION NUMBER 
HOST SESSION ID 


WS ZERO DB UNCHANGED 
DW NOT USED 
DW OO1H STRUCTURED FIELD TYPE, (DEST/ORIG) 
UNUSED 


WSOFFSD DW 
WSSEGTD DW 


OFFSET ADDRESS OF STRUCTURED FIELD DATA 
SEGMENT ADDRESS OF STRUCTURED FIELD DATA 


Sy tt et eT ee ee ee eT eT ee TY 


0 
0 
fe) 
0 
0 
0 
DW O 
0 
0 
0 
0 
0 
g 


DW UNUSED 
WSTASKID DW PC TASK ID 
DW 
DW DUP (0) ; SYSTEM WORK AREA 


DATASEG ENDS 


; *** MAIN BODY *** 


CODESEG SEGMENT PUBLIC 
; THESE ENTRY POINTS ARE LOCATED IN THE SECOND LOAD MODULE 
EXTRN INIT: NEAR ,CHECKERR: NEAR, GETSRESP: NEAR, CONNHOST: NEAR ,DISCHOST:NEAR, 
GRAFDATA: NEAR 
; THESE ENTRY POINTS ARE USED BY THE SECOND LOAD MODULE 
PUBLIC THESEND ,DISPD 
; ESTABLISH ADDRESSABILITY OF CODE 
ASSUME CS : CODESEG 


; ESTABLISH ADDRESSABILITY OF DATA BY DS AND ES REGISTER 


START: MOV AX , DATASEG 
MOV DS , AX 
MOV ES ,AX 


ASSUME DS : DATASEG, ES : DATASEG 


; RESOLVE NAMES FOR SERVICES AND FIND THE BASE WINDOW SESSION ID 
CALL INIT 


; DISPLAY THE DATA 
MAINLOOP: DISPMENU PCSESSID,MENUSPS 


; GET THE USERS REQUEST FROM THE MENU 


CALL GETSRESP 

; IS THE USER FINISHED? 

CMP AL,ESC ; DID THE USER HIT THE ESCAPE KEY? 
JNE CONT ; NO, PROCESS HIS REQUEST 

JMP THESEND ; YES, THE USER IS FINISHED, CLEAN UP 


; GET THE DATA, (CORRESPONDING TO THE USERS REQUEST) FROM THE HOST 
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CONT: GETDATA MFIC,KEYBOARD,HOSTSID,PCTASKID,STRTPROG, SENDACK, BUFFER 


; DISPLAY THE DATA 
DISPDATA FIRSTINP,SECNDINP 


; CONTINUE GETTING USER'S REQUEST 


JMP MAINLOOP 

THESEND: CALL CLEARSCR ; CLEAR THE SCREEN BEFORE EXITING 
MOV AX ,4CO0OH ; EXIT PROGRAM 
INT 21H 


*** PROCEDURE DEFINITIONS *** 


PROCEDURE: CLEARSCR 
FUNCTION : 
THIS PROCEDURE WILL CLEAR THE SCREEN. 


ee Ne Ne te Me Ne 


CLEARSCR PROC 


; SET THE SEGMENT TO THE BEGINNING OF THE HARDWARE BUFFER 
MOV AX, OBOOOH 
MOV ES , AX 


; INITIALIZE THE LOOP COUNTER 
MOV CX ,2000 ; THE BUFFER HAS 2000 CHARACTERS AND EACH 
; CHARACTER IS FOLLOWED BY AN ATTRIBUTE 


MOV DLO 

; MOVE A BLANK CHARACTER WITH AN ATTRIBUTE INTO THE BUFFER 
CLRSCRN: MOV BYTE PTR ES:[DI],' ' 

MOV BYTE PTR ES: [DI+1],07H 

; INCREMENT THE INDEX INTO THE BUFFER 

ADD O72 

; CLEAR THE WHOLE BUFFER 

LOOP CLRSCRN 

RET : RETURN TO CALLER 


CLEARSCR ENDP 


MACRO NAME : GETDATAM 
FUNCTION 

THIS PROCEDURE WILL PRINT A MESSAGE ON THE MENU SAYING 
THAT THE DATA IS BEING GOTTEN FROM THE HOST. 


et eT ee ee eT TY 


GETDATAM PROC 


; MOVE CURSOR TO THE PLACE THAT THE MESSAGE IS BEING PRINTED 


MOV DL,11 
MOV DH, 20 
MOVSCURS 
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; PRINT THE STRING 
MOV DX,OFFSET WAITMSG 


DOSFXN DISPSTRG 


RET ; TO CALLER 


GETDATAM ENDP 


END OF THE CODE SEGMENT 
IDENTIFY THE START ADDRESS OF THE SOURCE 


CODESEG ENDS : 
END START i 
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Chapter 29. Sample Program 5 


THIS PROGRAM IS THE SECOND MODULE OF THE STEMIR PROGRAM. THE 
TWO MODULES ARE TO BE ASSEMBLED SEPARATELY AND THEN LINKED TOGETHER. 


ae ek et et eT 


PAGE 60,132 


; KKEKK DATA KKKK 


DATASEG SEGMENT PUBLIC 
; DECLARE VARIABLES THAT ARE NEEDED BY THE FIRST MODULE OF THE PROGRAM 


PUBLIC PCSESSID,KEYBOARD ,MENUSPS,HOSTSID,PCTASKID,MFIC, IN1ISCNCD,SFSQSID 
PUBLIC FIRSTINP ,SECNDINP ,SESSMGR 


; DECLARE VARIABLES THAT ARE LOCATED IN THE FIRST MODULE OF THE PROGRAM 
EXTRN BUFFAREA: WORD ,CURRSY:WORD 


; PARAMETER LIST FOR CONNSKEY 


CKRETNCD DB 0 ; RETURN CODE 

CKFXNID DB O ; FUNCTION NUMBER 

CKSESSID DB 0 ; SESSION ID 

CKRESRV1 DB 0 ; RESERVED 

CKEVENTQ DW 0 ; EVENT QUEUE ID 

CKKEYSTQ DW 0 ; KEYSTROKE QUEUE ID 
CKOPTION DB 40H ; OPTION BYTE (INTERCEPT ALL) 
CKRESRV2 DB 0 ; RESERVED 


; PARAMETER LIST FOR CONNSSF 


CFRETNCD DB 0 ; RETURN CODE 
CEPANID DB O ; FUNCTION NUMBER 
CFSESSID DB 0 ; SESSION ID 
CFRESRV1 DB 0 ¢ MUST. BE: 30 
CFFLQID DW O ; FIXED-LENGTH QUEUE ID 
DW OOO1H ; MUST BE OQO001H 
CFEVNTS DW O600H ; EVENTS TO BE ENQUEUED - DFT 
CFORPLY DD QUERYREP ; OFFSET AND SEGMENT OF THE QUERY REPLY 
CFRESERV2 DW 0 ; MUST BE O 
CFTASKID DW 0 ? PC TASK ID 
CFRESRV3 DW 0 ; MUST BE O 
CFWORK DW 9 DUP(0) ; SYSTEM WORK AREA 
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; QUERY REPLY FOR DESTINATION/ORIGIN 


QUERYREP 


QRAPLNAM 


; PARAMETER LIST FOR CRTSQ 


DW 
DB 
DB 


CQOFFSET DW 0O 
COSEGMEN DW 0 


CONAME 


; PARAMETER LIST FOR DISCSKEY 


DKRETNCD 
DKFXNID 

DKSESSID 
DKRESRV1 
DKTASKID 
DKRESRV2 


; PARAMETER LIST FOR DISCSSF 


DFRETNCD 
DFFXNID 
DFSESSID 
DFRESERV1 


DFTYPE 


DFWORK 


; DEFINE 


DIRETNCD 
DIFXNID 
DISESID 
DIRESRVD 
DICONNID 


; DEFINE 
ETRETNCD 
EIFXNID 
EISESID 
EITRESRVD 
EICONNID 
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DB 


DB 
DB 
DB 
DB 
DW 
DB 


DB 
DB 
DB 
DB 
DW 
DW 
DW 
DW 


8 


O0O0000 


ooo00 


1900H 
81H 

9DH 

0 

01H 
OO008H 
0008H 
OFH 
4801H 

12 DUP(0O) 


DUP (0) 


0001H 


6 
i] 


DUP (0) 
DUP (0) 


et et ee ee) ee eT eT | TY 


LENGTH OF THE STRUCTURE 
QUERY REPLY 

ANOMALY IMPLEMENTATION 

MUST BE 0 

STRUCTURED FIELD EXCHANGE 

MAXIMUM NUMBER OF BYTES IN INBOUND TRANSMISSION 
MAXIMUM NUMBER OF BYTES IN OUTBOUND TRANSMISSION 
RESERVED 

MY OWN DESTINATION ORIGIN ID 

PC APPLICATION NAME IN EBCDIC 


OFFSET OF THE QUEUE 
SEGMENT ADDRESS OF THE QUEUE 
QUEUE NAME 


=e Ne NO 


RETURN CODE 
FUNCTION NUMBER 
SESSION ID 
RESERVED 
CONNECTOR'S TASK ID 
RESERVED 


a a i. el aT eT | 


RETURN CODE 

FUNCTION NUMBER 

SESSION ID 

RESERVED 

NOT USED 

DISCONNECT TYPE - DESTINATION/ORIGIN 
NOT USED 

SYSTEM WORK AREA 


et ee eT ee ee eT 


PARAMETER LIST FOR DISASINP 


DB 
DB 
DB 
DB 
DW 


oo00o00 


RETURN CODE 
FUNCTION CODE 
SESSION ID 
RESERVED 
CONNECTORS TASK ID 


=e Ne Ne Se Ne 


PARAMETER LIST FOR ENABSINP 


DB 
DB 
DB 
DB 
DW 


oOo0o00 


RETURN CODE 
FUNCTION ID 

SESSID 

RESERVED 
CONNECTOR'S TASK ID 


we Ne Ne Ne Ne 


; PARAMETER LIST FOR QUERYSID 
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QDRETNCD DB 0 ; RETURN CODE 

ODF XNID DB O ; FUNCTION NUMBER 
QDOPTION DB OQ ; OPTION BYTE 

QDDATA DB O ; DATA BYTE 

QDNAMOFF DW 0 ; OFFSET OF NAME TABLE 
QDNAMSEG DW 0 ; SEGMENT OF NAME TABLE 
QDLNGNAM DB_ 8 DUP(?) ; SESSION LONG NAME 


; PARAMETER LIST FOR QSBASSW 


QSRETNCD DB 0 ; RETURN CODE 
QOSFXNID DB O ; FUNCTION NUMBER 
QSENVID DB O ; ENVIRONMENT ID 
OSSESSID DB 0O ; SESSION ID 
QSWINDOW DB 0 ; WINDOW SHORT NAME 
QSRESERV DB 0 ; RESERVED 


; PARAMETER LIST FOR TRANSLAT 


TLRETNCD DB 0O ; RETURN CODE 

TLFXNID DB O ; FUNCTION NUMBER 

TLSRCOFF DW 0 ; OFFSET ADDRESS OF SOURCE BUFFER 
TLSRCSEG DW 0 ; SEGMENT ADDRESS OF SOURCE BUFFER 
TLTRGOFF DW 0O ; OFFSET ADDRESS OF TARGET BUFFER | 
TLTRGSEG DW 0 ; SEGMENT ADDRESS OF TARGET BUFFER 
TLTYPE DB 0 ; TRANSLATION TYPE 

TLRESERV DB 0 ; RESERVED 

TLLENGTH DW 0 ; LENGTH 

NAMARRAY DB 14 ; NAME ARRAY FOR QUERYSID FUNCTION 
NUMSESS DB 0 ; NUMBER OF MATCHING SESSIONS 

SHRTNAME DB 0 ; SESSION SHORT NAME 

SESSTYPE DB 0 ; SESSION TYPE 

SESSID DB e) ; SESSION ID 

SPARE DB ) 

LONGNAME DB 8 DUP(0) ; LONG NAME OF SESSION 

KYBDNAME DB 'KEYBOARD' ; PARM LIST FOR NAMESRES ON KEYBOARD 
SMGRNAME DB 'SESSMGR ' ; PARM LIST FOR NAMESRES ON SESSMGR 
XLATNAME DB 'XLATE : ; PARM LIST FOR NAMESRES ON XLATE 
MFICNAME DB "MFIC : ; PARM LIST FOR NAMESRES ON MFIC 
KEYBOARD DW 0 7; KEYBOARD SERVICE TYPE 

SESSMGR DW 0 7 SESSMGR SERVICE TYPE 

XLATE DW 0 ; XLATE SERVICE TYPE 

MFIC DW 0 ; MFIC SERVICE TYPE 

PCSESSID DB 0 ; SESSION ID OF THE GRAPHICS WINDOW 
HOSTSID DB 0 7 SESSION ID OF THE HOST WINDOW 
HOSTSWND DB 0 ; SHORT NAME OF THE HOST WINDOW 
PCTASKID DW 0 ; TASK ID FOR THIS PC PROGRAM 

COUNT DW 0 ; NUMBER OF BAR FIELDS ON THE X AXIS 
BFWIDTH DW 0 ; WIDTH IN PELS OF THE BAR FIELD 
BARWIDTH DW 0 ; WIDTH OF ONE BAR (3/4 OF BFWIDTH) 
HEIGHT DW 6) ; HEIGHT IN PELS OF A BAR 
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STARTX 
STARTY 


YAXISLEN 
YMAX 
IN1SCNCD 
SFSQSID 
SFSQOSLEN 
SFSQ 
HOSTQSID 
HOSTOQLEN 
HOSTQ 


FIRSTINP 
SECNDINP 


MENUSPS 
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DW 
DW 


DW 


DW 


DB 


DW 
DW 
DB 


DW 
DW 
DB 


DB 
DB 


DB 
DB 
DB 


DB 
DW 
DB 


DB 
DW 
DB 
DB 
DB 
DW 
DB 


DB 
DW 
DB 
DB 
DW 
DB 


DB 
DW 
DB 


DB 
DW 
DB 


DB 
DW 
DB 
DB 
DW 
DB 


0 ; 
0 

0 ; 
0 ; 
0 ; 


0 i 
64 ; 
64 DUP(O) ; 


0 ; 
64 ; 
64 DUP(0O) ; 


O i 
0 ; 


201,7 ; 
78 DUP(205,7) 
IST 47 


186,7 
78 DUP(0700H) 
186,7 


186,7 

30 DUP(0700H) 
oO pee Le peg ee 
"CT pA OO} 44 Rt 
Ep at Te AO! 
30 DUP(0700H) 
186,7 


igo ys] 

31 DUP(0700H) 
'G!,4,'R",4, 1A" 
1S) 45'0';,4,'°M" 
32 DUP(0700H) 
L386; 7 


186,7 
78 DUP(0700H) 
186,7 


186,7 
78 DUP(0700H) 
186,7 


186,7 
10 DUP(0700H) 


° 
, 


X POSITION OF THE LOWER LEFT CORNER OF THE BAR 
Y POSITION OF THE LOWER LEFT CORNER OF THE BAR 


LENGTH OF THE Y AXIS IN PELS 

MAXIMUM VALUE ON THE Y AXIS 

SCAN CODE FOR THE FIRST INPUT IN THE MENU 

ID OF THE HOST INTERACTIVE FIXEDSLENGTH QUEUE 
LENGTH OF THE HOST INTERACTIVE QUEUE 

THE HOST INTERACTIVE QUEUE 

ID OF THE HOST KEYSTROKE FIXEDSLENGTH QUEUE 
LENGTH OF THE HOST KEYSTROKE QUEUE 

THE HOST KEYSTROKE QUEUE 


THE CHARACTER IN THE FIRST INPUT FIELD 
THE CHARACTER IN THE SECOND INPUT FIELD 


THE PRESENTATION SPACE FOR THE SELECTION MENU 


4,'M',4,'I',4,'R',4,0,0 
45 DA NOs ARS phy A gS 
4,'N',4 


aj PY pag AY pag ee pay C4, O70 
4,'M',4,'A',4,'R',4,'Y',4 


"1',1,0,0,'-',1,0,0,'G',1,'R',1,'0',1,'S',1,'S',1,0,0 


TR yp oe pegs oe 
51 DUP(0700H) 
186,7 


pip yay! Nyy Ogle Eee 


DB 
DW 
DB 
DB 
DW 
DB 


DB 
DW 
DB 
DB 
DB 
DW 
DB 


DB 
DW 
DB 
DB 
DB 
DW 
DB 


DB 
DW 
DB 
DB 
DB 
DW 
DB 


DB 
DW 
DB 


DB 
DW 
DB 
DB 
DB 
DB 
DB 
DW 
DB 


DB 
DW 
DB 


DB 
DW 
DB 


DB 
DW 
DB 
DB 
DB 
DB 
DW 
DB 
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186,7 

10 DUP(0700H) 

12 ak pO Oy pO 07 Ne hee ly oT, 00 

PRY Oe ee ye ae a Oe ee D 

53 DUP(0700H) 

186,7 

186,7 

10 DUP(0700H) 

Le plyO pO, =" 1,0;0 7" N ae ane ge eee eg 
"Oo" gly VF ppg Pedy Re why O° pie Dy pg ly Cr gy a os a 
00,167 71, UM Rig ne Le” gk 


41 DUP(0700H) 
LEG: "7 


LB6y-7 

10 DUP(07 
"AY Aly oe Pal 
eS ply 
0,0, ut a 
41 DUP (0700 
186,7 


OOH 
Ras 
pas 
' 


~~ -O -~ 


f 
O 
H 


186,7 

10 DUP(07 
iS Ls oe Ohi 
wR ge 
ae oi 
43 DUP (0700H 
186,71 


0 


186,7 
78 DUP(0700H) 
186,7 


186,7 

10 DUP (0700H) 
ots 32 4 One 
oo Dees eae ams oe 
se ares he Dees OS 
0,0 

057 

36 DUP(0700H) 
186,7 


186,7 
78 DUP(0700H) 
186,7 


186,7 
78 DUP(0700H) 
186,7 


186,7 

10 DUP(0700H) 
10,0, 
070, °D* ,15 A“ 
ed eee oe: alae Ba 
050 1", EO" 
29 DUP(0700H) 
186,7 


Bd res ee 


,Li,0,0, 
7l,'T',1, 


peg I pbs 


Or lg 
Po pkg ep do ps Sk 


jE peg Me pepe Egle ba ply 
ply Vp dy Sg Ly pag yd 
pep pS at 


VET py 
aa aly 


OM pe ea lp Ot gg Se 
ply Nadie Bg le Se r 


a pag ep ey Go y 
Ps 8 Oe aaa mre yaw C) 
3 


; nog Ee pag B90 70 
A 
BPs gidig sw algee gad BAe ; Y 


eee 5072057342054 3% a3 


Rg chig pkg to 4 ioe rp. i ei if deg oy 
,1,0,0,'F',1,'O',1, , 

‘st, 1, pt, i. O, 
ist] 


1,'A 
rer 
pple Oy gig Ae ody ig dlp res ye 


eye Pe aaa leg i Eee 
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YMAXTAB 
PROGNAME 


HSTPRMPT 
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DB 
DB 


186,7 

10 DUP(0700H) 

tN ply gO pe = ep Oy Oy Dy glgtd gay Oo ye eS ele gles 
070,77 Dl ply A gdp DE ply AN yl 0,07 2 1,0" £77 R4 14,0; 
RE i EL Sedeg VETO pkg Oe gg diy SO spa gdege Oa p ay Op pt toe og 
OO per age Be te ket Ae he ER ee 

31 DUP(0700H) 

L86y7 


186,7 
78 DUP(0700H) 
186,7 


186,7 

10 DUP(0700H) 

Sh 328 3 hi poy Le pay CO poe Pe PO eOy yo ae, LE 933 7050 
rp 3 oy Mo eB p35 O07 05S Foe Polk foe N37 040 
205;3:;,20553;' oS" sas0 KU 

077 

42 DUP(0700H) 

186,7 


186,7 
78 DUP(0700H) 
186,7 


1867 
78 DUP(8400H) 
1365.7 


1865.7 
10 DUP(0700H) 


yt Re Sie ple Oe ye Se gt OO LORE pte Nee ete Eee ee 
CO SGT Pel Gp eel eS oo eZ Eads Oe O70 

DS pt pt ee pep Gi Pe FOG ee ee ee 
OO Se rg Ege rn pal ep ok 9 Fe a eg 

Dela he gly ple ee ea 

22 DUP(0700H) 

186,7 

186,7 

10 DUP(0700H) 

et Re] Ne Pet Od ge 27 O20 eB! 29 tS ee pia PO 

Mk el PaO, Op he ol pk eee pe oe 


51 DUP(0700H) 
186,7 


186,7 
78 DUP(0700H) 
186,7 
200,7 
78 DUP(205,7) 
18857 


80 DUP(0700H) 


100,40,15000,100,25,900,400,150, 300,125 
"STEMIR  .EXE' 


'ENTER THE SHORT NAME OF THE HOST WINDOW',13,10 
205,205,16,' $' 


Sample Program 5 


NOTDFT DB 13,10, 'INCORRECT HOST WINDOW SPECIFIED. WINDOW MUST BE A DFT '! 
DB "HOST SESSION.',13,10 
DB "PROGRAM TERMINATED',13,10,'S' 
ERRMSG DB 13,10,'ERROR IN API CALL. PROGRAM TERMINATED.',13,10,'S$' 
ASCI2SCN DB 45H,16H,1EH,26H, 25H, 2EH, 36H, 3DH, 3EH, 46H 


DATABUFF STRUC 


MNTHDATA DW 12 DUP(?) + DATA FOR THE LAST 12 MONTHS 
YEARDATA DW 5 DUP(?) ; DATA FOR THE LAST 5 YEARS 


DATABUFF ENDS 


DATASEG ENDS 


; #*** DEFINE: MACROS **** 


MACRO : DOSFXN 
FUNCTION : ; 
THIS WILL CALL A DOS FUNCTION SPECIFIED BY THE PARAMETER FXNNUM. 


br at eT eT | 


DOSFXN MACRO FXNNUM 
MOV AH, FXNNUM ; THE FUNCTION NUMBER BELONGS IN AL 
INT 21H ; CALL DOS 
ENDM 


MACRO : DISPLAY 
FUNCTION : 
DISPLAY THE CHARACTER STRING PASSED IN STRING. 


me Ne Se Ne ONO 


; ESTABLISH CONSTANTS 
DISPSTRN EQU 9 ; DOS DISPLAY STRING FUNCTION NUMBER 
DISPLAY MACRO STRING 


DX POINTS TO THE STRING TO BE DISPLAYED 
DISPLAY THE CHARACTER 


LEA DX,STRING 
DOSFXN DISPSTRN 


=e 68 


ENDM 


MACRO : DRAWSBOX 
FUNCTION 

DRAWS A FILLED IN BOX WITH ITS LOWER LEFT CORNER AT X0,YO WITH 
THE SPECIFIED HEIGHT AND LENGTH. THIS IS DONE BY DRAWING LENGTH — 
NUMBER OF VERTICAL LINES NEXT TO EACH OTHER EACH WITH LENGTH HEIGHT. 


ST et et et ee TY 
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; ESTABLISH CONSTANTS 
BARCOLOR EQU 2 ; THE COLOR OF THE BOX 
DRAWSBOX MACRO X0O,Y0O,HEIGHT, LENGTH 


MOV CX, LENGTH 


MOV STARTX , XO ; SAVE A COPY OF THE X STARTING OFFSET 
MOV AX, YO ; CALCULATE THE OFFSET FROM THE TOP OF THE SCREEN 
SUB AX ,HEIGHT 7 OF THE TOP OF THE BOX 
MOV STARTY , AX ; SAVE THE TOP OF BOX OFFSET 
NEXTLINE: PUSH CX ; SAVE THE COUNT 
DRAWVERT STARTX,STARTY ,HEIGHT,BARCOLOR 
POP CX ; RESTORE THE COUNT 
INC STARTX ; POINT STARTX TO THE NEXT COLUMN TO DRAW 
LOOP NEXTLINE ; DRAW THE NEXT LINE 
ENDM 


MACRO NAME : DRAWVERT 


PARAMETERS : X ~- VALUE ON THE X AXIS, (COLUMN) 
YBEGIN -- VALUE ON THE Y AXIS, (ROW) 
LEN -- LENGTH OF THE LINE 
COLOR -- COLOR OF THE LINE 

FUNCTION 


THIS WILL DRAW A VERTICAL LINE. THE LINE WILL BE DRAWN 
FROM POINT (X,YBEGIN) TO (X,YBEGIN + LEN). 


rT el St eT et a eT eT 


DRAWVERT MACRO X,YBEGIN, LEN, COLOR 
LOCAL LP,EXIT 
; SAVE THE CURRENT Y VALUE 
MOV AX, YBEGIN 
MOV CURRSY , AX 


; HAVE WE REACHED THE LAST PEL YET? 
MOV BX,LEN ; THE LAST PEL = THE FIRST PEL PLUS 
ADD BX,CURRSY a THE LENGTH OF THE LINE 

LP: CMP CURRSY,BX 


; YES, WE ARE DONE 
JE EXIT 


; NO, TURN THE PEL ON 
; INITIALIZE REGISTERS FOR THE BIOS WRITE DOT FUNCTION 


MOV CX ,X ; COLUMN NUMBER FOR VERTICAL LINE 
MOV AL ,COLOR ; COLOR FOR VERTICAL 
MOV AH ,WRITEDOT ; BIOS FUNCTION NUMBER 
MOV DX,CURRSY ; ROW NUMBER OF PEL 
INT 10H ; CALL THE BIOS VIDEO FUNCTION 
; INCREMENT THE ROW NUMBER AND CHECK THE PEL 
INC CURRSY 
JMP LP 
EXIT: NOP 
ENDM 
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MACRO : CHEK4ERR 
FUNCTION 
SET UP THE REGISTERS FOR THE ERROR CHECKER PROCEDURE. 


et a eT eT) 


CHEK4ERR MACRO RETNCODE 


IFNB <RETNCODE> ; IF THERE IS A PARAMETER LIST RETURN CODE 
MOV BL,RETNCODE r SPECIFIED, PASS THE RETURN CODE IN BL 
ELSE 

MOV BL,O ; OTHERWISE, SEND A O IN BL 

ENDIF 

CALL CHECKERR ; CALL THE ERROR CHECKER 

ENDM 


MACRO NAME : CONNSKEY 
PARAMETERS : SERVTYPE -- RESOLVED VALUE FOR 'KEYBOARD' 
SESSID -- SESSION ID 
FUNCTION : 
CONNECT THE KEYBOARD TO THE SPECIFIED SESSION. 


i en et ee eT TD 


CONNSKEY MACRO SERVTYPE,SESSID,KEYSTQ,EVNTQ 


; INITIALIZE PARAMETER LIST FOR CONNSKEY : 


MOV CKRETNCD , OOH ; RETURN CODE MUST = 0 BEFORE REQUEST 
MOV CKFXNID,0OOH ; FUNCTION ID MUST = O BEFORE REQUEST 
MOV AL,SESSID ; SESSION ID INTO THE LIST 


MOV CKSESSID,AL 


IFNB <KEYSTQ> 


MOV AX,KEYSTO ; IF A KEYSTROKE QUEUE WAS SPECIFIED, 
ELSE ; PUT IT INTO THE LIST 

MOV AX,0 

ENDIF 


MOV CKKEYSTQ , AX 


IFNB <EVNTQ> 


MOV AX ,EVNTO ; IF AN EVENT QUEUE WAS SPECIFIED, 
ELSE ; PUT IT INTO THE LIST 

MOV AX,0 

ENDIF 


MOV CKEVENTQ , AX 


; INITIALIZE REGISTERS FOR CONNSKEY 
MOV AH,O9H 

MOV AL,O1H 

MOV BH,80H 

MOV BL,20H 

MOV CX,0000H 
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MOV DX,SERVTYPE ; RESOLVED VALUE FOR 'KEYBOARD' 
MOV DI, SEG CKRETNCD ; SEGMENT ADDRESS OF PARAMETER LIST 
MOV ES,DI ;: IN ES 

MOV DI,OFFSET CKRETNCD ; OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR CONNSKEY SERVICE 
INT 7AH 


ENDM 


MACRO NAME : CONNSSF 


PARAMETERS : SERVTYPE -- RESOLVED VALUE FOR 'MFIC © , 
SESSID -- SESSION ID 
QUEUVEID -- FIXED-LENGTH QUEUE ID 
PCTAKSID -=- PC TASK ID 
PCAPLNAM -- PC APPLICATION NAME 

FUNCTION 


CONNECT TO THE SPECIFIED HOST SESSION FOR HOST INTER- 
ACTIVE SERVICES. THIS MACRO CONNECTS FOR DESTINATION/ORIGIN 
STRUCTURED FIELDS. DESTINATION/ORIGIN IS VALID FOR DFT 
HOST SESSIONS ONLY. 


bt a nt al Sat Mt at eT eT eT eT 7 


CONNSSF MACRO SERVTYPE,SESSID,QUEUEID , PCTASKID, PCAPLNAM 


; INITIALIZE PARAMETER LIST FOR CONNSSF 


MOV CFRETNCD,OOH ; RETURN CODE MUST = 0 BEFORE REQUEST 
MOV CFFXNID,OOH ; FUNCTION ID MUST = 0 BEFORE REQUEST 
MOV AL,SESSID ; SESSION ID INTO THE LIST 

MOV CFSESSID,AL 

MOV AX,QUEUEID ; FIXED-LENGTH QUEUE ID INTO THE LIST 
MOV CFFLQID,AX 

MOV AX,PCTASKID ; PC TASK ID INTO THE LIST 


MOV CFTASKID,AX 


TRANSLAT XLATE,PCAPLNAM,QRAPLNAM,O1H,12 
; TRANSLATE THE PC APPLICATION NAME INTO 
; EBCDIC AND PUT IT IN THE QUERY REPLY 


; INITIALIZE REGISTERS FOR CONNSSF 

MOV AH,O9H 

MOV AL,O1H 

MOV BH, 80H 

MOV BL, 20H 

MOV CX ,O0000H 

MOV DX, SERVTYPE ; RESOLVED VALUE FOR 'MFIC ' 

MOV DI, SEG CFRETNCD ; SEGMENT ADDRESS OF PARAMETER LIST 
MOV ES,DI : IN ES 

MOV DI,OFFSET CFRETNCD ; OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR CONNSSF SERVICE 
INT 7AH 


ENDM 
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se se Me we Ne Me we 


CRTSQ 


me Ne me Ne NO 


DELSENT 


eS et et eT eT 
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MACRO NAME : CRTSQ 
PARAMETERS : QUEUE -- THE QUEUE TO CREATE 
QSIZE -- SIZE OF QUEUE 
FUNCTION : 
CREATE A FIXED LENGTH QUEUE. 


MACRO QUEUE,QNAME ,QSIZE,RETURNID 


; INITIALIZE PARAMETER LIST FOR CRTS$Q 


MOV AX,SEG QUEUE ; SEGMENT ADDRESS INTO THE LIST 
MOV COSEGMEN , AX 
MOV AX,OFFSET QUEUE ; OFFSET INTO THE LIST 


MOV CQOFFSET, AX 


; INITIALIZE REGISTERS FOR CRTSQ 

MOV AH,0O4H 

MOV BL ,OOH ; NO NAME SPECIFIED 

MOV CX, ,QSIZE ; SIZE OF THE QUEUE 

MOV DX ,OOO0OH ; DX MUST = O FOR THE REQUEST 


MOV DI, SEG CQOFFSET SEGMENT ADDRESS OF PARAMETER LIST 
MOV ES,DI IN ES 


MOV DI,OFFSET CQOFFSET OFFSET OF PARAMETER LIST IN DI 


SIGNAL WORKSTATION PROGRAM FOR CRTSQ SERVICE 


. 
' 


INT 7AH 
MOV RETURNID,DX ; PASS THE QUEUE ID BACK TO THE CALLER 
ENDM 


MACRO NAME : DELSENT 
PARAMETERS : QUEID - FIXED LENGTH QUEUE ID 
FUNCTION: 

DELETE THE ENTRY FROM THE SYSTEM 


MACRO QUEID 
; INITIALIZE REGISTERS FOR DELSENT REQUEST 

MOV AH,O6H ; AH = X'06! 

MOV CX,0000H ; CX = X'0000' 

MOV DX,QUEID ; DX = FIXED LENGTH QUEUE ID 


; REQUEST THE DELSENT SERVICE 
INT 7AH 


ENDM 


MACRO NAME : DISCSKEY 
PARAMETERS : SERVTYPE -- RESOLVED VALUE FOR 'KEYBOARD' 
SESSID -- SESSION ID 
FUNCTION 
DISCONNECT THE KEY BOARD FROM THE SPECIFIED SESSION. 
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DISCSKEY MACRO SERVTYPE,SESSID,TASKID 


it et et eT ee et TY 


DISCSSF 
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; INITIALIZE PARAMETER LIST FOR DISCSKEY 


MOV DKRETNCD, OOH ; RETURN CODE MUST = O BEFORE REQUEST 
MOV DKFXNID, 00H ; FUNCTION ID MUST = O BEFORE REQUEST 
MOV AL,SESSID ; SESSION ID INTO THE LIST 


MOV DKSESSID,AL 


IFNB <TASKID> 


MOV AX, TASKID ; IF A TASK ID WAS SPECIFIED, PUT IT 
ELSE ; IN THE LIST 

MOV AX ,O000H 

ENDIF 


MOV DKTASKID , AX 


; INITIALIZE REGISTERS FOR DISCS$KEY 

MOV AH,09H 

MOV AL,O2H 

MOV BH,80H 

MOV BL,20H 

MOV CX,0000H 

MOV DX,SERVTYPE ; RESOLVED VALUE FOR 'KEYBOARD' 

MOV DI, SEG DKRETNCD  ; SEGMENT ADDRESS OF PARAMETER LIST 
MOV &ES,DI ; IN ES 

MOV DI,OFFSET DKRETNCD ; OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR DISCSKEY SERVICE 
INT 7AH 


ENDM 


MACRO NAME : DISCSSF 
PARAMETERS : SERVTYPE -- RESOLVED VALUE FOR 'MFIC : 
SESSID ~- SESSION ID 
FUNCTION : 
DISCONNECT FROM THE SPECIFIED HOST SESSION. THIS MACRO 
IS CODED TO DISCONNECT FROM A DESTINATION/ORIGIN CONNECTION. 


MACRO SERVTYPE,SESSID 


; INITIALIZE PARAMETER LIST FOR DISCSSF 


MOV DFRETNCD , OOH ; RETURN CODE MUST = O BEFORE REQUEST 
MOV DFFXNID,OOH ; FUNCTION ID MUST = O BEFORE REQUEST 
MOV AL,SESSID ; SESSION ID INTO THE LIST 


MOV DFSESSID,AL 


; INITIALIZE REGISTERS FOR DISCSSF 

MOV AH,O9H 

MOV AL,O2H 

MOV BH,80H 

MOV BL,20H 

MOV CX,0000H 

MOV DX,SERVTYPE ; RESOLVED VALUE FOR 'MFIC ' 

MOV DI, SEG DFRETNCD ; SEGMENT ADDRESS OF PARAMETER LIST 
MOV ES,DI ; IN ES 

MOV DI,OFFSET DFRETNCD ; OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR DISCSSF SERVICE 
INT 7AH 


ENDM 


al a nL Sd al St al St eT eT eT eT Td 
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MACRO NAME : DISASINP 
PARAMETERS : SERVTYPE - RESOLVED VALUE FOR 'KEYBOARD' 
SESSID - SESSION ID 
CONNSID - (OPTIONAL) CONNECTORS TASK ID IS 
NEEDED ONLY IF THE TASK THAT REQ- 
UESTED THE CONNECT TO KEYBOARD FOR 
THIS SESSION IS DIFFERENT FROM THE 
TASK REQUESTING THE DISABLE INPUT. 
FUNCTION : 
USE THIS SERVICE TO DISABLE OPERATOR INPUT TO THE 
SESSION. 


DISASINP MACRO SERVTYPE,SESSID,CONNSID 


bt a eT et eT et eT ee eT eT et eT TY 


MOV AX,SEG DIRETNCD ; ADDRESSABILITY OF 
MOV ES, AX ; PARAMETER LIST 
MOV DI,OFFSET DIRETNCD ; USING ES:DI 


; INITIALIZE PARAMETER LIST FOR DISABLE INPUT 

MOV DIRETNCD, OOH RETURN CODE MUST=0O ON REQUEST 
MOV DIFXNID,OOH FUNCTION ID MUST=0 ON REQUEST 
MOV AL,SESSID KEYBOARD INPUT DISABLED FOR 
MOV DISESID,AL THIS SESSION 

IFNB <CONNSID> IF THERE IS A CONNECTORS ID 
MOV AX, CONNSID THEN PUT IT IN THE 

MOV DICONNID, AX PARAMETER LIST 

ENDIF 


bt iT et et eT eT) 


; INITIALIZE REGISTERS FOR DISABLE INPUT 

MOV AX ,0905H ; LOCK INPUT SERVICE 

MOV BX, 8020H 

MOV CX ,0000H 

MOV DX, SERVTYPE ; DX=NAME RESOLUTION FOR THE 
; KEYBOARD SERVICES 

; REQUEST DISABLE INPUT SERVICE 


INT 7AH 


ENDM 


MACRO NAME : ENABSINP 
PARAMETERS : SERVTYPE - RESOLVED VALUE FOR 'KEYBOARD' 
SESSID - SESSION ID 
CONNSID - (OPTIONAL) THE CONNECTORS TASK ID IS 
NEEDED ONLY IF THE TASK THAT RE- 
QUESTED THE CONNECT TO KEYBOARD FOR 
THIS SESSION IS DIFFERENT FROM THE 
TASK REQUESTING THE ENABLE INPUT 
FUNCTION 
USE THIS SERVICE TO ENABLE OPERATOR INPUT TO THE 
SESSION. 


ENABSINP MACRO SERVTYPE,SESSID,CONNSID 


MOV AX,SEG EITRETNCD ; ADDRESSABILITY OF 
MOV ES , AX 7; PARAMETER LIST 
MOV DI,OFFSET EIRETNCD ; USING ES:DI 
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; INITIALIZE PARAMETER LIST FOR ENABLE INPUT 

MOV EIRETNCD,0OOH RETURN CODE MUST=0 ON REQUEST 
MOV EIFXNID,0O0OH FUNCTION ID MUST=0 ON REQUEST 
MOV AL,SESSID KEYBOARD INPUT DISABLED FOR 
MOV EISESID,AL THIS SESSION 

IFNB <CONNSID> IF THERE IS A CONNECTOR'S ID 
MOV AX, CONNS$ID THEN STORE THE ID 

MOV EICONNID,AX IN THE PARAMETER LIST 

ENDIF 


“eo te Ne Ne Ne Ne Ne 


; INITIALIZE REGISTERS FOR ENABLE INPUT 

MOV AX ,O0906H ; ENABLE INPUT SERVICE 

MOV BX ,8020H 

MOV CX ,0000H 

MOV DX, SERVTYPE ; DX=NAME RESOLUTION FOR THE 
4 KEYBOARD SERVICES 

; REQUEST ENABLE INPUT SERVICE 


INT 7AH 
ENDM 
MACRO ~ NAMESRES 


PARAMETERS - NRSSERVN - LOCATION OF THE 8 BYTE 
SERVICE NAME. I.E.'SESSMGR ' 
NRSSERVT - RETURN CODE FROM PARAMETER LIST 


we Ne Ne Ne Ne Ne 


NAMESRES MACRO NRSSERVN ,NRSSERVT 


; SET UP REGISTERS NAMESRES 


MOV AX,SEG NRSSERVN ; SEGMENT ADDRESS OF PARAM. LIST 
MOV ES ,AX ; ES = SEGM ADDRESS OF PARAM.LIST 
MOV AH,81H ; AH = x'81! 

MOV CX ,0000H ; CX = xX'0000' 

MOV DI,OFFSET NRSSERVN ; DI = OFFSET ADDR. OF PARAM LIST 
; REQUEST SERVICE TYPE FROM WORKSTATION PROGRAM 

INT 7AH 

; RETURN SERVICE TYPE ID TO CALLER 

MOV NRSSERVT, DX 
ENDM 


MACRO NAME : QUERYSID 


PARAMETERS : SERVTYPE -- RESOLVED VALUE FOR 'SESSMGR ' 
NAMEARRY -- NAME ARRAY 
OPTION -~- OPTION BYTE 
DATA -~- DATA BYTE 
LONGNAME -~- SESSION LONG NAME 
FUNCTION 


GET THE SESSION ID(S) OF THE SESSION(S) SPECIFIED BY 
THE OPTION AND DATA BYTES AND RETURNS THEM IN THE NAME 
ARRAY. 
NOTE: THE NAME ARRAY IS SET UP BY THE USER AND MUST HAVE 
THE LENGTH OF THE ARRAY CONTAINED IN THE 1ST BYTE. 


Oe ee ey ee eT ee eT | eT eT eT eT eT 
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QUERYSID 
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OSBASSW 
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MACRO SERVTYPE,NAMEARRY ,OPTION , DATA, LONGNAME 


; INITIALIZE PARAMETER LIST FOR QUERYSID 

MOV QDRETNCD,OOH RETURN CODE MUST = 0 BEFORE REQUEST 
MOV QDFXNID,OOH FUNCTION ID MUST = 0 BEFORE REQUEST 
MOV AL,OPTION OPTION BYTE INTO THE LIST 

MOV QDOPTION,AL 

MOV AL,DATA ; DATA BYTE INTO THE LIST 

MOV QDDATA,AL 

MOV AX,OFFSET NAMEARRY ; NAME ARRAY OFFSET INTO THE LIST 

MOV QDNAMOFF,AX 

MOV AX,SEG NAMEARRY ; NAME ARRAY SEGMENT INTO THE LIST 
MOV QDNAMSEG,AX 


~e Me Ne 


IFNB <LONGNAME> ; CHECK IF A LONG NAME WAS SPECIFIED 


CLD ; COPY DIRECTION = FORWARD 
MOV AX,SEG QDLNGNAM 
MOV ES,AX 

MOV DI,OFFSET QDLNGNAM 
MOV SI,OFFSET LONGNAME 


ES:DI POINTS TO DESTINATION IN PARM 
LIST 
DS:SI POINTS TO SOURCE OF LONG NAME 


~e Ne Ne Ne ON 


MOV CX,8 MOVE 8 BYTES 
MOVSB COPY LONG NAME INTO THE PARM LIST 
ENDIF 


; INITIALIZE REGISTERS FOR QUERYSID 

MOV AH,0O9H 

MOV AL,O1H 

MOV BH, 80H 

MOV BL,20H 

MOV CX ,0000H 

MOV DX, SERVTYPE ; RESOLVED VALUE FOR 'SESSMGR ' 

MOV DI, SEG QDRETNCD ; SEGMENT ADDRESS OF PARAMETER LIST 
MOV ES,DI ; IN ES 

MOV DI,OFFSET QDRETNCD ; OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR QUERYSID SERVICE 
INT 7AH 


ENDM 


MACRO NAME : QSBASSW 
PARAMETERS : SERVTYPE -- RESOLVED VALUE FOR 'SESSMGR ' 
FUNCTION 

FIND THE SESSION ID AND SHORT NAME FOR THE BASE WINDOW 
OF AN ENVIRONMENT. 


MACRO SERVTYPE 
; INITIALIZE PARAMETER LIST FOR QSBASSW 


MOV QSRETNCD, OOH ; RETURN CODE MUST 
MOV QSFXNID,0OOH ; FUNCTION ID MUST 


O BEFORE REQUEST 
0 BEFORE REQUEST 


Ital 
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QOSBASSW 


RESOLVED VALUE FOR 'SESSMGR ' 

SEGMENT ADDRESS OF PARAMETER LIST 
IN ES 

OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR QSBASSW SERVICE 


; INITIALIZE REGISTERS FOR 
MOV AH,O9H 

MOV AL,OAH 

MOV BH, 80H 

MOV BL,20H 

MOV CX,OFFH 

MOV DX,SERVTYPE ; 
MOV DI, SEG QSRETNCD ; 
MOV ES,DI F 
MOV DI,OFFSET QSRETNCD ; 
INT  7AH 

ENDM 


MACRO NAME OSTASK 
PARAMETERS NONE 
FUNCTION 


“we “Ne Se Me Ne Ne 


RESOLVED VALUE FOR 


GET THE ID OF THE CURRENT ACTIVE TASK. 


"XLATE i 


TYPE OF TRANSLATE 
NUMBER OF BYTES TO TRANSLATE 


TRANSLATE THE DATA IN A BUFFER FROM ASCII CODES TO 


OSTASK MACRO 
; INITIALIZE REGISTERS FOR QS$TASK 
MOV AH,9CH 
; SIGNAL WORKSTATION PROGRAM FOR QSTASK SERVICE 
INT  7AH 
ENDM 
; MACRO NAME : TRANSLAT 
; PARAMETERS : SERVTYPE -- 
; SOURCE  -- SOURCE BUFFER 
; TARGET -- TARGET BUFFER 
; TYPE -- 
; LENGTH -- 
: FUNCTION 
: MFI CODES, OR FROM MFI CODES TO ASCII CODES. 
TRANSLAT MACRO SERVTYPE,SOURCE,TARGET,TYPE,LENGTH 


; INITIALIZE PARAMETER LIST FOR TRANSLAT 


MOV TLRETNCD,OOH ; 
MOV TLFXNID,OOH ; 
MOV AX,OFFSET SOURCE ; 
MOV TLSRCOFF,AX 

MOV AX,SEG SOURCE ; 
MOV TLSRCSEG,AX 

MOV AX,OFFSET TARGET ; 
MOV TLTRGOFF,AX 

MOV AX,SEG TARGET ; 
MOV TLTRGSEG,AX 

MOV AL,TYPE ; 
MOV TLTYPE,AL 

MOV AX,LENGTH ; 
MOV TLLENGTH,AX 
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RETURN CODE MUST 
FUNCTION ID MUST 
SOURCE OFFSET INTO 


0 BEFORE REQUEST 
O BEFORE REQUEST 
THE LIST 


SOURCE SEGMENT INTO THE LIST 
TARGET OFFSET INTO THE LIST 
TARGET SEGMENT INTO THE LIST 
TRANSLATION TYPE INTO THE LIST 


LENGTH INTO THE LIST 
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; INITIALIZE REGISTERS FOR TRANSLAT 

MOV AH,O9H 

MOV AL,O1H 

MOV BH, 80H 

MOV BL, 20H 

MOV CX, OFFH 

MOV DX, SERVTYPE ; RESOLVED VALUE FOR 'XLATE A 

MOV DI, SEG TLRETNCD ; SEGMENT ADDRESS OF PARAMETER LIST 
MOV ES,DI ; IN ES 

MOV DI,OFFSET TLRETNCD ; OFFSET OF PARAMETER LIST IN DI 


; SIGNAL WORKSTATION PROGRAM FOR TRANSLAT SERVICE 
INT 7AH 


ENDM 
. k*kKK CODE **** 
CODESEG SEGMENT PUBLIC 
; DECLARE ENTRY POINTS THAT ARE NEEDED BY THE FIRST MODULE OF THE PROGRAM 
PUBLIC INIT ,CHECKERR , GETSRESP , CONNHOST , DISCHOST , GRAFDATA, CONNSF 
; DECLARE ENTRY POINTS THAT ARE LOCATED IN THE FIRST MODULE OF THE PROGRAM 
EXTRN THESEND: NEAR 


ASSUME CS:CODESEG,DS:DATASEG,ES:DATASEG 


XSVERTEX EQU 50 ; X,Y CO-ORDINATES OF THE VERTEX OF THE GRAPH 
YSVERTEX EQU 167 

LENXAXIS EQU 260 ; LENGTH IN PELS OF THE X AXIS 

LENYAXIS EQU 160 ; LENGTH IN PELS OF THE Y AXIS 

WRITEDOT EQU OCH ; BIOS FUNCTION NUMBER FOR WRITING A DOT 


; PROCEDURE : INIT 

; CALLED BY : MAIN 

: FUNCTION 

; THIS PROCEDURE DOES THE INITIAL WORK NEEDED FOR THIS PROGRAM. 

; FIRST, IT FINDS THE RESOLVED VALUES FOR THE KEYBOARD, SESSION INFOR- 
; MATION, HOST INTERACTIVE, AND TRANSLATE SERVICES. THEN IT PROMPTS 

' THE USER FOR THE SHORT NAME OF THE HOST WINDOW. NEXT IT FINDS THE 

: SESSION IDS FOR THIS PC SESSION AND FOR THE HOST SESSION. IT CHECKS 
; TO MAKE SURE THE HOST CONNECTION IS FOR DFT. LAST IT FINDS THE TASK 
; ID FOR THIS PC APPLICATION. 

i 

, 


ESTABLISH CONSTANTS 


DFTTYPE EQU 02H ; NUMBER TO INDICATE SESSION IS DFT HOST 
INKEY EQU O1H ; DOS INPUT KEY WITH ECHO FUNCTION NUMBER 
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INIT PROC NEAR 
|e 2a at A i a i 2 222 2 ZZ D2 222 2 2 2222 22) 
7; FIND THE RESOLVED VALUES FOR KEYBOARD, SESSION MANAGER, TRANS- 23 
3; LATE, AND HOST INTERACTIVE SERVICES. os 


ee ee ee er 


Cr re A A ee A Ae A A A A A A A A A A ee A A A ee A A A A 


NAMESRES KYBDNAME,KEYBOARD 
; FIND THE RESOLVED VALUE FOR KEYBOARD SERVICES 
CHEK4ERR 


NAMESRES SMGRNAME,SESSMGR 
; FIND THE RESOLVED VALUE FOR SESSION INFORMATION 
: SERVICES 

CHEK4ERR 


NAMESRES XLATNAME,XLATE 
; FIND THE RESOLVED VALUE FOR TRANSLATE SERVICES 
CHEK4ERR 


NAMESRES MFICNAME ,MFIC 
; FIND THE RESOLVED VALUE FOR HOST INTERACTIVE 
: SERVICES 

CHEK4ERR 


ee eo 


Prorvrrrvrerrvrrrrrvrervrrvrerrererrervrvrerrererseaeaee aera ahaa ahahaha 


;; PROMPT THE USER FOR THE SHORT NAME OF THE HOST WINDOW. GET THE ;; 
;; USER'S RESPONSE AND CONVERT IT TO UPPER CASE. 7 


ee 


Ce Ae A Ae a A A A A 2 


DISPLAY HSTPRMPT ; PROMPT THE USER FOR THE HOST WINDOW SHORT NAME 


DOSFXN INKEY ; GET THE USERS RESPONSE IN AL 

CMP AL," * ; CHECK IF THE CHARACTER IS UPPER CASE 

JL OKINPUT ; IF SO, STORE IT 

ADD AL, A's". * ; OTHERWISE, CONVERT IT TO UPPERCASE 
OKINPUT: MOV HOSTSWND , AL ; SAVE THE HOST WINDOW SHORT NAME 


Ce ee 


Ce ee ae Ae Ae A A A A A A 


; FIND THE SESSION ID AND TYPE OF THE SPECIFIED HOST WINDOW. IF ; 
+ THE SESSION TYPE IS NOT DFT THEN DISPLAY AN ERROR MESSAGE AND : 
; EXIT. THE HOST CONNECTION MUST BE DFT SINCE THIS PROGRAM USES : 
; DESTINATION/ORIGIN STRUCTURED FIELDS WHICH CAN ONLY BE USED WITH ; 
; DFT HOST CONNECTIONS. ; 


Ce ee ee 


CA A rr A A A Ae A A A A A A A 


QUERYSID SESSMGR,NAMARRAY,01H,HOSTSWND 
; GET THE HOST SESSION ID AND TYPE 
CHEK4ERR QDRETNCD 


CMP SESSTYPE,DFTTYPE 
; CHECK IF THIS HOST IS DFT 
JE OKHOST 


DISPLAY NOTDFT ; IF NOT, DISPLAY AN ERROR MESSAGE AND EXIT 
JMP THESEND 
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OKHOST: 


INIT 


A eS eT eT eT eT a ST OT Tt BT a nt a i eT a Ma Sa St at Mt St nt Sa a 
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MOV AL,SESSID ; MOVE THE HOST SESSION ID TO HOSTSID 
MOV HOSTSID,AL 


Ce 


Cr A A A A A re A Ae A A A A A A ee 
7; FIND THE SESSION ID FOR THIS PC SESSION. i? 


oeceereeoe eee ewe eee see woe wee ewe sw eee eee ese ee er ee ese eee ere eee ee se ee ee we we wm ee we eww ew 


tr A A A A A A A A ee ee De A A 2 A A A A A a A 


QSBASSW SESSMGR  ; GET THE SESSION ID FOR THIS PC SESSION 
CHEK4ERR QSRETNCD 


MOV AL,QSSESSID ; MOVE THE PC SESSION ID TO PCSESSID 
MOV PCSESSID,AL 


ee 


tr Ae ae ee Ae te A ZA A A A A A 2 ee A A 


;; FIND THE TASK ID FOR THIS PC PROGRAM. i? 


eooeer eee eee eee ere eee eee eee eee eee eee eee eee ee ee ee we ee ew ee ee eee ee ee ele tl tll el tl el 


| Ae Ae ee A A 


OSTASK ; GET THIS PC APPLICATION'S TASK ID 
MOV PCTASKID,DX ; SAVE THE TASK ID IN PCTASKID 

RET 

ENDP 


PROCEDURE : GETSRESP 
CALLED BY : MAIN 
FUNCTION : 

THIS PROCEDURE GETS THE USERS RESPONSES TO THE MENU SELECTIONS. 
IT STARTS BY SETTING THE CURSOR AT THE FIRST INPUT FIELD. IT THEN 
WAITS FOR THE USER TO PRESS A KEY. IF THE KEY WAS THE ESCAPE KEY, 
MEANING USER WISHES TO EXIT THE PROGRAM, THEN THE PROCEDURE RETURNS 
TO THE CALLER. IF THE KEY WAS THE PC ENTER KEY, MEANING THE USER 
WANTS THE SELECTED DATA TO BE DISPLAYED, THEN A CHECK IS MADE TO 
MAKE SURE BOTH INPUT FIELDS ARE NOT BLANK. IF BOTH ARE NOT BLANK, 
THEN THE PROCEDURE RETURNS TO THE CALLER. IF AT LEAST ONE FIELD IS 
BLANK, THEN A BEEP IS ISSUED TO SIGNAL AN ERROR AND THE PROCEDURE 
LOOPS BACK TO READ IN ANOTHER CHARACTER. THIS KEEPS THE USER FROM 
TRYING TO DISPLAY DATA WITHOUT SPECIFYING WHICH DATA ARE TO BE DIS- 
PLAYED. 

WHEN ENTERING INPUT INTO THE FIRST FIELD, A CHECK IS MADE TO 
MAKE SURE THE INPUT CHARACTER IS BETWEEN '1' AND '‘5'. IF THE CHAR- 
ACTER IS NOT IN THIS RANGE, A BEEP IS ISSUED AND THE PROCEDURE LOOPS 
BACK TO READ IN ANOTHER CHARACTER. IF THE CHARACTER IS WITHIN RANGE 
‘THE CHARACTER IS DISPLAYED ON THE MENU AND THE CURSOR IS MOVED TO 
THE SECOND INPUT FIELD. THE CHARACTER ENTERED IN THE SECOND INPUT 
FIELD IS CHECKED TO MAKE SURE IT IS EITHER A 'Y' OR AN 'M'. AS IN 
THE CASE FOR THE FIRST FIELD, A BEEP IS ISSUED ON AN ERROR, OTHER- 
WISE THE CHARACTER IS DISPLAYED ON THE MENU AND THE CURSOR IS MOVED 
TO THE FIRST INPUT POSITION. 
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; ESTABLISH CONSTANTS 


BEEP 

CR 

ESC 
DISPCHAR 
INNOECHO 
SETCURS 
IN1ROW 
IN1COL 
IN2ROW 
IN2COL 


GETSRESP 


INPUTCHR: 


QUIT: 
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EQU 
EQU 
EQU 
EQU 
EQU 


O7H 


we Ne Ne 8 Ne Ne Ne Ne Ne Ne 


ASCII FOR A BEEP CHARACTER 

ASCII FOR A CARRIAGE RETURN 

ASCII FOR AN ESCAPE 

DOS DISPLAY CHARACTER FUNCTION NUMBER 
DOS INPUT WITH NO ECHO FUNCTION NUMBER 
BIOS SET CURSOR POSITION FUNCTION NUMBER 
ROW CO-ORDINATE FOR 1ST INPUT AREA 
COLUMN CO-ORDINATE FOR 1ST INPUT AREA 
ROW CO-ORDINATE FOR 2ND INPUT AREA 
COLUMN CO-ORDINATE FOR 2ND INPUT AREA 


eesevreeereeeeer eee eee tee eee ee ees ee see eer eres ee eee eee er eer eee eer eae eee ee eee eeee 


CA A re A A A A A A A A A Ze A 2 2 A 


;; CLEAR THE INPUT VARIABLES. : ; 
7; SET THE CURSOR AT THE FIRST INPUT FIELD. ; 


er er 


Cr re a A A A A A A A A A A 2 A A A 


MOV 
MOV 


MOV 
MOV 
MOV 
MOV 
INT 


FIRSTINP,O 
SECNDINP,0O 


DH, INLROW 
DL, IN1COL 
BH,0 
AH, SETCURS 
10H 


CLEAR THE FIRST INPUT VARIABLE 
CLEAR THE SECOND INPUT VARIABLE 


DH, DL = ROW, COLUMN OF THE CURSOR 


BH = DISPLAY PAGE NUMBER = 0 


Cr ee 


THE MAIN PROGRAM. 
IS ON THE FIRST INPUT, GO TO THE CODE TO HANDLE THE FIRST INPUT 
FIELD, OTHERWISE GO TO THE CODE TO HANDLE THE SECOND INPUT FIELD. ; 


; GET THE USER'S RESPONSE. IF THE ESCAPE KEY WAS HIT THEN RETURN  ; 
; TO THE MAIN PROGRAM. IF THE ENTER KEY WAS HIT THEN CHECK THE ; 
; INPUT FIELDS TO MAKE SURE THE USER HAS ENTERED BOTH INPUTS. IF =; 
; EITHER INPUT IS BLANK THEN BEEP AT THE USER, OTHERWISE RETURN TO ; 


IF ANY OTHER KEY WAS HIT, THEN IF THE CURSOR 


ee 


~ 
~ 


DOSFXN 


CMP 
JE 


INNOECHO 


AL, ESC 
QUIT 


AL,CR 
NOTDONE 


FIRSTINP,O 
BADKEY 


SECNDINP,O 
BADKEY 


° 
, 


Cr A ee A A A A A A A 


GET AN INPUT CHARACTER INTO AL 


CHECK IF IT IS THE ESC KEY 
IF SO, EXIT 


CHECK IF IT IS THE ENTER KEY 
IF NOT, CONTINUE PROCESSING THE INPUT KEY 


CHECK IF THE FIRST INPUT FIELD IS EMPTY 
IF SO, BEEP AT THE USER AND TRY FOR ANOTHER KEY 


CHECK IF THE SECOND INPUT FIELD IS EMPTY 
IF SO, BEEP AT THE USER AND TRY FOR ANOTHER KEY 


RETURN TO THE CALLER 


NOTDONE : 


ONINPUT1: 


BADKEY : 


ONINPUT2: 


CMP 
JE 
JMP 
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DH, INLROW ; CHECK IF THE CURSOR IS ON THE FIRST INPUT FIELD 
ONINPUT1 ; IF NOT, GO TO THE SECTION FOR HANDLING THE 2ND 
ONINPUT2 : INPUT FIELD 


Ce 


~ 
~ 


, 


CMP 
JL 
CMP 
JG 


MOV 


MOV 
SUB 
MOV 
MOV 
MOV 


MOV 
DOS 


MOV 
MOV 
MOV 
INT 


rProtrervrrvrrvrrrrerrrvrerervrvrvrevrerrevrrvrrerrrererererereaeaeaeeaeeeeaeeeeaeeaee eee eee eae eee 


THE CURSOR IS ON THE FIRST 


USER HAS ENTERED A VALID SELECTION, I.E. THE CHARACTER IS BETWEEN; 
'1' AND '5'. IF THE CHARACTER IS OUT OF RANGE THEN GO TO THE ; 
CODE THAT BEEPS AT THE USER. OTHERWISE, SAVE THE CHARACTER IN : 
FIRSTINP, CONVERT THE CHARACTER TO A SCAN CODE AND SAVE IT IN ; 
IN1SCNCD, AND DISPLAY THE CHARACTER ON THE MENU. THEN MOVE THE ; 
CURSOR TO THE SECOND INPUT FIELD AND LOOP BACK TO GET ANOTHER : 


INPUT FIELD. CHECK TO MAKE SURE THE ; 


CHARACTER. 

Yr Aa Aa a 2 2 2 22 ZZ 2 2 2 2 2 2 2 2 2 22 22 2 22 2 22 2 2 2 2 2 2 2 2 
AL,'1' ; CHECK IF THE CHARACTER IS BETWEEN '1' AND '5! 
BADKEY ; IF NOT, BEEP AT THE USER AND TRY FOR ANOTHER 
AL,'5! ; CHARACTER 
BADKEY 
FIRSTINP,AL ; SAVE THE CHARACTER IN FIRSTINP 
BL,AL ; USE THE BINARY VALUE OF THE ASCII CHARACTER 
BL,'1'-1 ; AS AN INDEX INTO THE ASCII TO SCAN CODE TABLE 
BH,O 
DL, ASCI2SCN[BX] 

INISCNCD,DL ; SAVE THE SCAN CODE IN INISCNCD 
DL, AL ; DISPLAY THE CHARACTER ON THE SCREEN 
FXN DISPCHAR 
DH, IN2ROW ; MOVE THE CURSOR TO THE SECOND INPUT FIELD 
DL, IN2COL 
AH, SETCURS 
10H 
INPUTCHR 


oeer eer eee eer eae ee wee ese eee eee ese ee eee ee eee ee eee ee ee ee ew ew ee ww ew www wee Be He we Hw Bw 


THIS CODE BEEPS AT THE USER TO INDICATED THAT AN INCORRECT KEY i? 
WAS PRESSED. TO BEEP, A CTRL-G (07H) IS SENT TO THE DISPLAY. i? 
THEN LOOP BACK TO GET ANOTHER CHARACTER. i} 


ee ee 2 


Ct a Ae Ae Ae ZZ A A A A A A 


MOV 
DOS 
JMP 


DL, BEEP ; BEEP AT 
FXN DISPCHAR 


THE USER TO SIGNAL AN ERROR 


INPUTCHR ; GET ANOTHER INPUT CHARACTER 


ee ed 


te A A At Ae A A A ee A A A A 


THE CURSOR IS ON THE SECOND INPUT FIELD. CONVERT THE CHARACTER 
IN AL TO UPPER CASE. CHECK TO MAKE SURE THE USER HAS ENTERED A 
VALID SELECTION, I.E. THE CHARACTER IS EITHER AN 'M' OR A 'Y'. 


IF THE CHARACTER IS OUT OF 


AT THE USER. OTHERWISE, SAVE THE CHARACTER IN SECNDINP AND DIS- 
PLAY THE CHARACTER ON THE MENU. THEN MOVE THE CURSOR TO THE 


FIRST INPUT FIELD AND LOOP 


RANGE THEN GO TO THE CODE THAT BEEPS ; 


BACK TO GET ANOTHER CHARACTER. 


eevee ereeren eee eee eee ees e wore ee ee ewe eee eee ee ee eee ee oe we ew He ee we eee ee eee eo eee ee 8 


~ 
~ 


CMP 
JL 
SUB 


Prorvrrrrvrrvevrrprerevetvrrrrvrervrrrrevvrerrvrvrervrrrerrerevrrrevrevvervrervrvrerererrereeea ss 


~ 


Alt ; CHECK IF THE CHARACTER IS LOWER CASE 


ISUPPER ; IF NOT, 
AL,' '-'A' ; CONVERT 


SKIP CONVERTING TO UPPER CASE 
TO UPPER CASE 
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ISUPPER: CMP AL,'M' 
JE OKKEY 
CMP AL,'Y' 
JNE  BADKEY 


CHECK IF THE CHARACTER IS EITHER AN 'M' OR A 'Y' 

IF NOT, BEEP AT THE USER AND TRY FOR ANOTHER 
CHARACTER 

GET ANOTHER INPUT CHARACTER 


we te te we 


OKKEY: MOV SECNDINP , AL ; SAVE THE CHARACTER IN SECNDINP 
MOV DL,AL ; DISPLAY THE CHARACTER ON THE SCREEN 
DOSFXN DISPCHAR 
MOV DH, INLROW 7 MOVE THE CURSOR TO THE FIRST INPUT FIELD 


MOV DL,IN1COL 
MOV AH ,SETCURS 
INT 10H 


JMP INPUTCHR ; GET ANOTHER INPUT CHARACTER 


GETSRESP ENDP 


PROCEDURE : GRAFDATA 
CALLED BY : DISPDATA 
FUNCTION 
THIS PROCEDURE DISPLAYS THE BARCHART OF THE DATA OBTAINED FROM 
THE HOST. FIRST IT GETS THE SELECTED TIME SPAN. IF IT IS BY MONTH, 


THEN THERE ARE TWELVE BARS ON THE GRAPH. IF IT IS BY YEAR, THEN 
THERE ARE FIVE BARS ON THE CHART. THE X AXIS IS DIVIDED INTO THE 
EITHER FIVE OR TWELVE SECTIONS DEPENDING ON THE SELECTION. EACH OF 


THESE SECTIONS IS A BAR FIELD. THE BASE OF A BAR TAKES UP THE LATER 
3/4 OF THE BAR FIELD. EXAMPLE: 


Y 


Bar Field | 1/4 | 3/4 | 


SI IS USED TO POINT TO THE STARTING POSITION OF EACH BAR. ET £5 
THE OFFSET IN PELS OF THE X POSITION OF THE LOWER LEFT CORNER OF THE 
BAR. SI STARTS BY POINTING 1/4 OF THE WAY INTO THE FIRST BAR FIELD. 
IT IS THEN INCREMENTED BY THE LENGTH OF THE BAR FIELD SO THAT IT 
POINTS 1/4 OF THE WAY INTO THE NEXT FIELD. 

DI IS USED TO POINT TO THE DATA OBTAINED FROM THE HOST. THE 
DATA FROM THE HOST IS 17 WORDS, 12 WORDS OF MONTH DATA FOLLOWED BY 
5 WORDS OF YEAR DATA. DI IS SET TO POINT TO THE FIRST 
DATUM OF THE MONTH DATA IF THE USER SELECTED THE MONTH TIME 
SPAN OR TO THE FIRST 
DATUM OF THE YEAR DATA IF THE USER SELECTED THE YEAR TIME SPAN. DI 
IS THEN INCREMENTED BY 2 AS EACH DATUM IS GRAPHED. 

THE HEIGHT OF EACH BAR DEPENDS ON THE MAGNITUDE OF THE DATUM 
BEING GRAPHED RELATIVE TO THE MAXIMUM VALUE ON THE Y AXIS. TO CAL- 
CULATE THE NUMBER OF PELS NEEDED TO REPRESENT A DATUM THE FOLLOWING 
COMPUTATION IS USED: 


DATUM VALUE 
# -PELS “=: S43 <HSSSesee-oSe X NUMBER OF PELS IN THE Y AXIS 
MAXIMUM Y VALUE 


ry ee ee ey 7 TT rT PT rh eT eT YT | eT eT 
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SINCE DIVISION AND MULTIPLICATION ARE FOR INTEGERS, THE ABOVE DIVI- 
SION WILL YIELD A ZERO QUOTIENT SINCE THE DATUM VALUE IS ALWAYS LESS 
THAN OR EQUAL TO THE MAXIMUM VALUE. THIS IS NOT GOOD SINCE THE NUM- 
BER OF PELS WOULD THEN BE ZERO. AN ACCURATE ESTIMATE OF THE FRAC- 
TION IS NEEDED TO ACCURATELY DETERMINE THE NUMBER OF PELS. TO SOLVE 
THIS, THE DATUM IS SHIFTED TO THE LEFT 1 WORD (MULTIPLIED BY 
65,536) BEFORE THE DIVISION AND THE RESULTING NUMBER OF PELS IS 
SHIFTED RIGHT 1 WORD (DIVIDED BY 65,536). THE SHIFTING IS ACCOM- 
PLISHED BY LOADING THE DATUM INTO THE DX REGISTER (THE HIGH WORD FOR 
WORD DIVISION), INSTEAD OF THE AX REGISTER, BEFORE THE DIVISION AND 
TAKING THE RESULT FROM THE DX REGISTER (THE HIGH WORD FOR WORD MUL- 
TIPLICATION), INSTEAD OF THE AX REGISTER, AFTER THE MULTIPLY. THE 
ALGORITHM THEN BECOMES: 


(DATUM VALUE X 65,536) 
RR L“(“ OIA —O ee OOOO :—sO=XSOCNUMBER OOF PELS IN THE Y AXIS [|X 65,536 
MAXIMUM Y VALUE 


THE MAXIMUM Y VALUE IS OBTAINED FROM A TABLE THAT CONTAINS THE 
MAXIMUM Y VALUE FOR EACH OF THE TEN GRAPHS. THE VALUES IN THE INPUT 
FIELDS ARE USED TO CALCULATE AN INDEX INTO THE TABLE. THE TABLE HAS 
THE MAXIMUM VALUES FOR THE MONTH OPTIONS 1, 2, 3, 4, AND 5 FOLLOWED 
BY THE MAXIMUM VALUES FOR THE YEAR OPTIONS 1, 2, 3, 4, AND 5. 


bk i i i ik i i BL i i i nS St i eS i nt et eT | i! eT eT 


GRAFDATA PROC NEAR 


Ck ee 


+; FIND WHICH TIME SPAN THE USER SELECTED. IF IT IS BY MONTH THEN ;; 
;; SET THE NUMBER OF BARS (COUNT) TO 12 AND POINT DI TO THE START OF;; 
7; THE MONTH DATA. IF IT IS BY YEAR THEN SET THE NUMBER OF BARS TO ;; 
77 5 AND POINT DI TO THE START OF THE YEAR DATA. ii 


Ce ee eS 


Frrrprrrrrprrreev perv rvrerrrevrerewevrererer eae eee eee eee aaa aaa 


CMP SECNDINP, 'M' ; CHECK IF 12 MONTH TIME SPAN WAS SELECTED 
JE BYMONTH 
MOV CX ;5 ; IF 5 YEAR TIME SPAN, LOAD THE COUNT (CX) 


; WITH 5 TO DISPLAY 5 BARS 
LEA DI ,BUFFAREA. YEARDATA 

; POINT DI TO THE BEGINNING OF THE YEAR DATA 
JMP FINDWIDT 


BYMONTH: MOV Cx; Lz ; IF 12 MONTH TIME SPAN, LOAD THE COUNT (CX) 
; WITH 12 TO DISPLAY 12 BARS 
LEA DI ,BUFFAREA.MNTHDATA 
; POINT DI TO THE BEGINNING OF THE MONTH DATA 


Ce 


; DIVIDE THE X AXIS INTO COUNT NUMBER OF BAR FIELDS. CALCULATE 1/4 ;; 
; OF A BAR FIELD AND 3/4 OF A BAR FIELD. POINT SI 1/4 OF THE WAY ;; 
; INTO THE FIRST BAR FIELD. 33 


Ce ee 


te ae A 


STORE THE NUMBER OF BARS FOR DIVISION 

CLEAR DX FOR DOUBLE WORD DIVISION 

DIVIDE THE X AXIS INTO COUNT NUMBER OF 
DIVISIONS. EACH OF THESE DIVISIONS IS A 
BAR FIELD 

STORE THE LENGTH OF THE BAR FIELD IN BFWIDTH 

BX = LENGTH OF THE BAR FIELD 


FINDWIDT: MOV COUNT,CX 
MOV Dx,0 
MOV AX,LENXAXIS 
DIV COUNT 


MOV BFWIDTH , AX 
MOV BX ,AX 


~e “NO Ne Ne SO Ne Ne 
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DONTADD: 


NEXTBAR: 


GRAFDATA 
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AL,1 
AL, 1 


BX, AX 
BARWIDTH , BX 


SI,XSVERTEX 
SI ,AX 


CALCULATE 1/4 OF THE BAR FIELD . 
AX = 1/4 OF THE BAR FIELD 


CALCULATE 3/4 OF BAR FIELD (BFWIDTH-1/4BFWIDTH) 
THIS IS THE WIDTH OF ONE BAR 


POINT SI TO THE START OF THE X AXIS 
SI POINTS 1/4 OF THE WAY INTO FIRST BAR FIELD 


ee ee ee er) 


7; GET THE MAXIMUM Y VALUE FOR THE SELECTED GRAPH. 

;; INPUTS TO AN INDEX, FIRST FIND THE BINARY VALUE OF THE FIRST 
77 INPUT AND SUBTRACT 1. 

;; FROM THE FIRST INPUT. 

7; USE THIS INDEX INTO THE TABLE TO OBTAIN THE MAXIMUM Y VALUE. 


TO CONVERT THE 


THIS IS DONE BY SUBTRACTING AN ASCII 


THEN, IF THE SECOND INPUT IS A 'Y' ADD 5. 


r 
ar 
af 

se as 73 
ae 
aa 


ee 


tr A fe Ae ee A A A A 


MOV 
MOV 
SUB 
CMP 
JE 

ADD 
ADD 


MOV 


MOV 


BH,O 
BL,FIRSTINP 
BX, "1" 
SECNDINP,'M' 
DONTADD 
BX,5 

BX ,BX 


~ eo Ne Ne Ne 


e 
ra 


e 
, 


AX, YMAXTAB [BX] 


YMAX , AX 


GET THE USER'S CHOICES FROM THE MENU 
USE THESE AS AN INDEX INTO A TABLE THAT GIVES 
THE MAXIMUM Y VALUES 


1M->1, 2M->2, ...,5M->5,1Y->6,2Y->7, ...,5Y->10 


DOUBLE BX SINCE THE TABLE ENTRIES ARE WORDS 
INDEX INTO THE TABLE TO GET THE OFFSET OF THE 
PROPER TABLE AND... 


GET THE MAXIMUM Y VALUE FOR THIS GRAPH 
SAVE IT IN YMAX 


Ce 


Cr ae A A Ae A A A A A A A 2 2 


;; GRAPH EACH OF THE DATA. ; 
7; CAN BE USED FOR MULTIPLICATION. ; 
7; IT'S HEIGHT IN PELS AND DRAW A BOX WITH THAT HEIGHT AND A BASE OF;; 
;; BARWIDTH. ; 
;; STARTING POINT OF EACH BOX. ; 


FIRST, STORE LENYAXIS IN MEMORY SO IT ae 
THEN, FOR EACH DATUM CALCULATE ;; 


SI IS INCREMENTED ALONG THE X AXIS TO POINT TO THE ee 


DI IS INCREMENTED THROUGH THE HOST ;; 


CX COUNTS THE NUMBER OF BARS TO DISPLAY. e° 


oe ee eee eee eee ee ee eee wee eee ee ee eee eee eee eee eee ee ee ee ee ee ese ee ee ew wee Be ee ow 


DATA. 

MOV AX, LENYAXIS 
MOV YAXISLEN , AX 
MOV DX, [DI] 

MOV AX,0 

DIV YMAX 

MUL YAXISLEN 
MOV HEIGHT, DX 
PUSH CX 


° 
f 


. 
’ 


se we Ne Ne Ne Ne 


. 
/ 


5 ae Ae ee Ae A A Se A A A A A A A 2 A 


STORE THE CONSTANT LENYAXIS IN MEMORY FOR 
THE UPCOMING MULTIPLIES 


PUT A HOST DATUM INTO DX (SHIFTED LEFT 1 WORD) 
CLEAR AX FOR DOUBLE WORD DIVISION 
CALCULATE THE NUMBER OF PELS NEEDED TO 
REPRESENT THIS VALUE 
SAVE DX (RESULT SHIFTED RIGHT 1 WORD) IN HEIGHT- 
THE HEIGHT IN PELS OF THE BAR 


SAVE THE BAR COUNT 


DRAWSBOX SI,YSVERTEX,HEIGHT,BARWIDTH 


POP 
ADD 
ADD 
LOOP 
RET 


ENDP 


CX 


SI,BFWIDTH 
DI,2 
NEXTBAR 


° 
’ 
° 
Ul 


. 
, 


. 
‘ 


. 
t 


DRAW THE BOX - LOWER LEFT CORNER = 
HEIGHT = HEIGHT, WIDTH = BARWIDTH 
RESTORE THE BAR COUNT 


(SI,YSVERTEX) 


POINT SI TO 1/4 OF THE WAY INTO NEXT BAR FIELD 
POINT DI TO THE NEXT WORD IN THE DATA 


Oy et et et et ee et eT eT er TY 


CONNHOST 


CONNSF: 


CONNHOST 


St et Tt en eT eT eT TY 


DISCHOST 


PROCEDURE 
CALLED BY 


FUNCTION 


THIS PROCEDURE DOES THE SET UP 


HOST. 
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CONNHOST 
GETDATA 


FOR GETTING THE DATA FROM THE 


FIRST IT CREATES A QUEUE FOR HOST INTERACTIVE COMMUNICATION 
AND THEN CONNECTS TO THE HOST INTERACTIVE SERVICES. 
A QUEUE FOR THE HOST KEYSTROKES AND CONNECTS 
THEN IT DISABLES THE USER INPUT TO THE HOST KEYBOARD 


NEXT IT CREATES 
TO THE HOST KEYBOARD. 
SO THAT THIS 


PROGRAM'S INPUT TO THE HOST IS NOT DISRUPTED. 


PROC 


CRTSQ 


CHEK4ERR 
CONNSSF 
CHEK4ERR 
CRTSQ 
CHEK4ERR 
CONNSKEY 
CHEK4ERR 
DISASINP 
CHEK4ERR 
RET 


ENDP 


PROCEDURE 
CALLED BY 


FUNCTION 


SF$Q,,SFSQSLEN,SFSQ$ID 
; CREATE A QUEUE FOR HOST INTERACTIVE 
; COMMUNICATION 


MFIC,HOSTSID,SFSQSID,PCTASKID , PROGNAME 
; CONNECT FOR HOST INTERACTIVE SERVICES 
CFRETNCD 


HOSTQ, ,HOSTOLEN , HOSTQSID 
; CREATE A QUEUE FOR HOST KEYSTROKES 


KEYBOARD , HOSTSID,HOSTQSID 
; CONNECT TO THE HOST KEYBOARD 
CKRETNCD 


KEYBOARD, HOSTSID 
; DISABLE USER INPUT TO THE HOST KEYBOARD 
DIRETNCD 


DISCHOST 
GETDATA 


THIS PROCEDURE DOES THE CLEAN UP FROM GETTING THE DATA FROM THE 


HOST. 


FIRST IT REENABLES USER INPUT TO THE HOST KEYBOARD. 


NEXT IT 


DISCONNECTS FROM THE HOST KEYBOARD AND DELETES THE KEYSTROKE QUEUE. 


THEN IT DISCONNECTS FROM HOST INTERACTIVE SERVICES 


AND DELETES THE 


HOST INTERACTIVE COMMUNICATION QUEUE. 


PROC 

ENABSINP 
CHEK4ERR 
DISCSKEY 
CHEK4ERR 


DELSENT 
CHEK4ERR 


KEYBOARD ,HOSTSID 
; ENABLE USER INPUT TO THE HOST KEYBOARD 
EIRETNCD 


KEYBOARD ,HOSTSID 
; DISCONNECT FROM THE HOST KEYBOARD 
DKRETNCD 


HOSTQSID ; DELETE THE HOST KEYSTROKE QUEUE 
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DISCHOST 


a i SL a at Sy iT BT Sat ST Se! eT eT eT eT 


CHECKERR 


ERROR: 


CHECKERR 


CODESEG 
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DISCSSF MFIC,HOSTSID 
7 DISCONNECT FROM HOST INTERACTIVE SERVICES 
CHEK4ERR DFRETNCD 


DELSENT SFSQSID ; DELETE THE HOST INTERACTIVE COMMUNICATION Q 
CHEK4ERR 


RET 


ENDP 


PROCEDURE : CHECKERR 


FUNCTION 
THIS PROCEDURE IS PASSED TWO RETURN CODES IN CL AN BL. BL CON- 
TAINS A RETURN CODE FROM THE FIRST BYTE IN A PARAMETER LIST. BOTH 


CL AND BL ARE CHECKED FOR O'S. IF EITHER CONTAINS A NON-ZERO RETURN 
CODE, AN ERROR MESSAGE IS DISPLAYED AND THE PROGRAM IS TERMINATED. 


NOTE: THIS IS A VERY SIMPLE ERROR HANDLER USED TO PRESERVE PROGRAM 
FLOW AND IS NOT LISTED AS AN EXAMPLE OF AN APPROPRIATE ERROR 
HANDLER. THIS ERROR HANDLER SIMPLY TERMINATES THE PROGRAM 
WHEN AN ERROR IS ENCOUNTERED LEAVING ANY RESOURCES, SUCH AS 
FIXED LENGTH QUEUES, PRESENTATION SPACES, AND A CONNECTION 
TO THE WINDOW SERVICES, STILL ALLOCATED. A MORE APPROPRIATE 
ERROR HANDLER WOULD DELETE ALL RESOURCES BEFORE TERMINATING. 


PROC NEAR 

CMP CL,0O ; CHECK THE RETURN CODE IN CL 
JNE ERROR 

CMP BL,O ; CHECK THE PARAMETER LIST RETURN CODE 
JNE ERROR 

RET 

DISPLAY ERRMSG ; DISPLAY THE ERROR MESSAGE 
INT 20H ; EXIT TO DOS 

ENDP 

ENDS 

END 


Part 5. Appendixes 


Part 5 contains additional information that deals with the Application 
Program Interface (API). 


Appendix A, “Scan-Code/Shift-State and ASCII/ASCII-Mnemonic 
Values,” describes the scan code/shift state values and the ASCII/ASCII 
mnemonics that can be sent to a session or intercepted from the 
keyboard for a particular session. 


Appendix B, “Destination/Origin Structured Fields,” describes the 
destination/origin structured field formats and protocol to use with the 
host interactive services. 


Appendix C, “Using Command Procedures for Save and Restore and for 
File Transfer,” describes ways to create programmed command 
procedures for using the Save, Restore, Send, and Receive commands. 


Appendix D, “Technical Notes,” contains technical information on the 
3270 capabilities of the IBM 3270 Personal Computer and describes the 
3270 data stream functions. 


Appendix E, “Problem Determination Procedures and Debugging 
Information,” describes problem determination procedures to use if a 
system error occurs during API activity in your application program, 
and describes some of the control blocks and data areas used by the 
workstation program that may assist you in debugging your application 
program or system extension. 


Appendix F, “Presentation Space Considerations,” describes 
presentation space considerations. 


Part 5. Appendixes 


Appendix G, “Calling Save, Restore, Send, and Receive from Your 
Application Program,” describes how to use DOS function calls to call 
Save, Restore, Send, and Receive from your application program. 


Appendix H, “Return Codes,” describes the return codes that can be 
received while the workstation program or application programs that 
use the API services are running. 


Appendix I, “Outbound Data Stream Preprocessor (ODSP) Option,” 
describes how to preprocess outbound data streams using ODSP. 


Appendix A. Scan-Code/Shift-State and 
ASCII/ASCII-Mnemonic Values 


THEPOUUCHIONE 6c 4 core Gee dee ein Hy SEO ORES TEAR ORE MESA BS ED HO A-2 
Scan-Code/Shift-State Values ....... 0... cc cece ee eee ee eee A-2 
DOA MONE” ee a yet kel Bas 6 Satna, State Flere a Reed ete ee See hae es A-2 
Specis) Seat’ Codes: sc 4.06% see ban eee ROE Ra RA A-3 
DME SUALE: Schaar tes eGR A EE Mae Cane ae ae wee A-4 
ASCII/ASCII Mnemonics .......... 0c cece ee ee eee eens A-4 
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Appendix A. Scan-Code/Shift-State and ASCII/ASCII-Mnemonic Values A-1 


Introduction 


Introduction 


Keystrokes sent to a session or read from the keyboard for a particular 
session via the Read and Write API are in the form of: 


e Scan-code/shift-state values or 
e ASCII/ASCII-mnemonic values. 
If you are using the Keyboard Services API, then applications using the 


API must be well-behaved. If you are using the API to another PC session, 
then that PC session must also be well-behaved. 


Scan-Code/Shift-State Values 


Scan Code 


A-2 


Keystrokes sent in the form of scan code/shift state are represented by a 
4-byte value. Byte 0 is the scan code, and byte 1 is the shift state. Bytes 2 
and 3 are normally ‘01’ and ‘00’, respectively; these two bytes are not 
needed for the Write Keystroke service requests. 


The scan code is a unique 1-byte hexadecimal value that is assigned to each 
key position on the IBM 3270 PC Keyboard, the Enhanced PC Keyboard, 
the PC XT Keyboard, and the Personal Computer AT Keyboard. Foldouts 
at the back of this book show the key position number and scan code for 
each key position on the keyboards. 


Figures A-1 and A-2 list the default scan code values for each key position 
for the PC and MFI modes, respectively, of the IBM 3270 PC Keyboard. 
Figures A-3 and A-4 list the default value for each key position for the PC 
and MFI modes, respectively, of the IBM Enhanced PC Keyboard. Figures 
A-5 and A-6 list the default value for each key position for the PC and MFI 
modes, respectively, of the PC XT Keyboard. Figures A-7 and A-8 list the 
default value for each key position for the PC and MFI modes, respectively, 
of the Personal Computer AT Keyboard. The first byte of the 2-byte 
keystroke value represents the default scan code; the second byte, the shift 
state; and the function (if there is one) is listed last. In Figure A-4 for 
example, the uppercase keystroke value for key 5 is: 

2521 $ 


Scan Code Function 


Shift State 


Special Scan Codes 


The Scan Code 


Note: The tables indicate the default values you will receive when reading 
the keyboard as well as the values you can send to a session. If you 
have modified the keyboard with the Keyboard Definition Utility, then 
the values you receive when reading the keyboard will differ. 


The workstation program uses some special scan codes not listed in 
Figure A-1 on page A-5. They are: 


e X‘7F’, which is used by the workstation program to tell keystroke 
applications that the shift state may have changed since the last key 
was sent. Your application should adjust the shift state to match the 
one accompanying the X‘7F”’ scan code if it is concerned with the shift 
state. 


e X‘F0’, which indicates that a key is breaking (being released), and the 
next keystroke to be sent is the key being released. 


e X‘00’, which indicates that the application or keyboard did not handle a 
series of rapid keystrokes, and some keystrokes were lost. 


In all sessions except for personal computer sessions, all keys are “make 
only,” with the exception of the following keys, which are “make/break”: 


The Upshift keys (left and right) 
The Alt key 

The Ctrl] key 

The Caps Lock key. 


When in the personal computer session, the keyboard is reprogrammed to 
make all keys that are sent to the personal computer session “make/break” 
as well as typematic. Therefore, an application program that uses the Read 
Input service to obtain keystrokes destined for a personal computer session 
should expect to receive three separate scan codes for each key that is 
pressed. The scan codes generated each time a key is pressed and released 
are as follows: 


1. When a key is pressed, the scan code for that key is generated. This 
scan code is continuously generated until the key breaks (is released). 


2. When the key breaks (is released), the X‘F0’ scan code is generated. 


3. Finally, the scan code of the key that was pressed is generated again to 
indicate that this key is breaking. 


In all other sessions, only one scan code is received for most keys. The 


“make/break” sequence of three scan codes only appears for the keys listed 
as “make/break” keys above. 


Appendix A. Scan-Code/Shift-State and ASCII/ASCII-Mnemonic Values A-3 


The Shift State 


Shift State 


The shift state is a 1-byte value that indicates which of the functions or 
characters printed on the keytop of a given position is being sent. The 
following shows the format of the shift state byte: 


CE Ee ee Se 6 
Reserved | Right Left Control | Alt Caps Upshift 
shift shift key keys Lock keys 


Bits 0 and 1 are reserved. 


Bit 2 represents the right upshift key. 
Bit 3 represents the left upshift key. 
Bit 4 represents the Control shift state. 
Bit 5 represents the Alt shift state. 
Bit 6 represents the Caps Lock state. 
Bit 7 represents the upshift state. Bit 7 indicates that one of the two 
upshift keys was pressed. If your application program must distinguish 
between the right upshift key and the left upshift key, use bits 2 and 3. 
Lower shift is represented by a value of X‘00’. 

Note: When sending keystrokes to another session, only bits 4 through 7 

control the shift state. Bits 2 and 3 are used by the PC sessions and 


PC application programs to determine which of the two shift keys 
caused the upshift state condition represented by bit 7. 


ASCII/ASCII Mnemonics 


A-4 


The ASCII/ASCII mnemonic is the 1- to 6-byte value representing the 
functions on the keyboard. Figures A-9 and A-10 list the ASCII/ASCII 
mnemonics that are common for all countries. Figure A-11 lists the 
additional ASCII/ASCII mnemonics that can be used by U.S. English. 


The tables give the ASCII code (both decimal and hexadecimal) and the 
ASCII mnemonic and specify the functions they perform in PC, 
Host/Notepad, and Work Station Control sessions. 


Scan Code Tables 


Default Scan Codes for the IBM 3270 PC Keyboard (PC 


Mode) 


ey 


Figure A-1 (Part 1 of 4). Default Scan Codes for IBM 3270 PC Keyboard 
(PC Mode) 


K 
0 
23 
4 
5 
6 
8 
0 


7 
1 
1 
1 
1 
1 
i! 
1 
1 
1 
2 
2 
2 
2 
2 
2 
2 
2 
3 
3 
3 
3 
3 


0 
1 
2 
3 
5 
6 
7 
8 
9 
1 
2 
7 
1 
2 
3 
4 


30 
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Scan Code Tables 


A-6 


> 


1300 < 1321 > 1304 


1A00 2 


|47__ | 2200 x 2221 X 
2 
149 | 2A00 v 2A21 V 2A04 
f51 «| 3100 n 3121 N 3104 


3A00 m 3A21 M 3A04 
4100 , 4121 < 4104 
4900 . 4921 4904 


3200 b 3221 B 
4A00 | 4A21 2? 4A04 


5900 Right Shift 5921 Right Shift 5904 Right Shift © 


1100 1104 Quit 
1900 Left Alt 1921 Left Alt 1904 Left Alt 
2900 Spacebar 2921 Spacebar 2904 Spacebar 


2004 Right Al 


Figure A-1 (Part 2 of 4). Default Scan Codes for IBM 3270 PC Keyboard 
(PC Mode) 


Key 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 
48 
49 
50 
51 
52 
53 
54 
55 
57 
58 
61 
62 
64 
65 
67 
70 
71 
72 
73 
74 
75 


Scan Code Tables 


Figure A-1 (Part 3 of 4). Default Scan Codes for IBM 3270 PC Keyboard 
(PC Mode) 


Key 
76 
78 
81 
82 
83 
84 
85 
88 
91 
92 
93 
95 
97 
100 
101 
102 
103 
104 
105 
106 
107 
108 
110 
111 
112 
113 
114 
115 
116 
117 
118 
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Scan Code Tables 


A-8 


*This key position is not used. 


Key 
119 
120 
121 
122 
123 
124 
125 
126 
127 
128 
129 
130 
131 
132 
133 


Figure A-1 (Part 4 of 4). Default Scan Codes for IBM 3270 PC Keyboard 
(PC Mode) 


Scan Code Tables 


Default Scan Codes for the IBM 3270 PC Keyboard (MFI 


Mode) 


Note: MFI = host/notepad. 


Cy 
Fa 0 
ES 2 EY 


1B2i 8 


Figure A-2 (Part 1 of 4). Default Scan Codes for IBM 3270 PC Keyboard 
(MFI Mode) 
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Scan Code Tables 


A-10 


0100 Enlarge 0121 Enlarge 0104 Window 
Delete 


Figure A-2 (Part 2 of 4). Default Scan Codes for IBM 3270 PC Keyboard 
(MFI Mode) 


Key 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 
48 
49 
50 
51 
52 
53 
54 
55 
57 
58 
61 
62 
64 
65 
67 
70 
71 
72 
73 
74 


Scan Code Tables 


6100 PAI e721 Dup 
6400 Left Tab 6421 Left Tab 


6100 Left Cursor 6121 Left Cursor 6104 Fast Left 
Cursor 


6A00 Right Cursor | 6A21 Right Cursor | 6A04 Fast 
Right Cursor 


Figure A-2 (Part 3 of 4). Default Scan Codes for IBM 3270 PC Keyboard 
(MFI Mode) 


Key 
75 
76 
78 
81 
82 
83 
84 
85 
88 
91 
92 
93 
95 
97 
100 
101 
102 
103 
104 
105 
106 
107 
108 
110 
111 
112 
113 
114 
115 
116 
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Scan Code Tables 


A-12 


3F00 PF8 3F21 PF8 3F04 


4700 PF9 4721 PF9 4704 Reverse 
Video 


4F00 PF10 4F21 PF10 4F04 Blink 
5600 PF11 5621 PF11 5604 Underscore 


5E00 PF12 5E21 PF12 5EK04 Attribute 
Reset 


*This key position is not used. 


Key 
117 
118 
119 
120 
121 
122 
123 
124 
125 
126 
127 
128 
129 
130 
131 
132 
133 


Figure A-2 (Part 4 of 4). Default Scan Codes for IBM 3270 PC Keyboard 
(MFI Mode) 


Scan Code Tables 


Default Scan Codes for the IBM Enhanced PC Keyboard 


(PC Mode) 


ical A 


Figure A-3 (Part 1 of 3). Default Scan Codes for IBM Enhanced PC 
Keyboard (PC Mode) 


7 
2 
2 
2 
2 
2 
2 
2 
2 
2 
2 
3 
3 
3 


Key 
10 
11 
12 
13 
15 
16 
17 
18 
19 
0 
1 
2 
3 
4, 
5 
6 
4 
8 
9 
0 
1 
32 
3 
34 
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Scan Code Tables 


A-14 


sca 7 


Figure A-3 (Part 2 of 3). Default Scan Codes for IBM Enhanced PC 
Keyboard (PC Mode) 


3200 b 3221 B 3204 


K 
3 
3 
3 
3 
3 
4 
4 
4 
4 
4 
4 
4 
4 
5 
5 
5 
5 
5 
5 
5 
5 
6 
6 
6 
7 
7 
7 
8 
8 
8 
8 


ey 
5 
6 
7 
8 
9 
0 
1 
3 
4 
6 
i 
8 
9 
0 
1 
2 
3 
4 
5 
7 
8 
1 
2 
4 
5 
6 
9 
1 
3 
4 
5 
91 


Scan Code Tables 


(Autokey) 


Note: Key 124 in the control state toggles Screen Echo. Key 126 in the control state is 
Break.* 


9 


Key 
92 
93 
95 
7 
100 
101 
102 
103 
104 
105 
106 
108 
110 
112 
113 
114 
115 
116 
117 
118 
119 
120 
121 
122 
123 
124 
125 
126 


Figure A-3 (Part 3 of 3). Default Scan Codes for IBM Enhanced PC 
Keyboard (PC Mode) 
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Scan Code Tables 


Default Scan Codes for the IBM Enhanced PC Keyboard 


(MFI Mode) 


A-16 


10 
i 
12 
1 


Key 


1 
i 
i 
i 
i 


204 


Figure A-4 (Part 1 of 3). Default Scan Codes for IBM Enhanced PC 
Keyboard (MFI Mode) 


2 
2 
22 
23 
2 

25 
2 

27 
8 


1 
4 
6 
2 

29 
0 


3 
3 
3 
3 


iL 
2 
3 
4 


3 


Scan Code Tables 


fies 
36 3300 h 3321 H 3304 


37 3B00 j 3B21 J 3B04 
1300 1 (BOI L 


10 
r 
re 
rm 
16 
ri 
8 
19 
50 
zi 

[naa Reset 


a 
z 
r 
76 


79 6100 Cursor Left 6121 Cursor Left 6104 Fast Cursor 
Left 


5 
$3 
24 
: 


6A00 Cursor Right {| 6A21 Cursor Right | 6A04 Fast Cursor 
Right 


0700 PF1 7721 NumLk 0704 PSA 


Figure A-4 (Part 2 of 3). Default Scan Codes for IBM Enhanced PC 
Keyboard (MFI Mode) 
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Sean Code Tables 


A-18 


fa [aFoo PFs [sb 7 —~*(oros PSB 
[2 [a7o0 PP7 [25004 ——~S~S~* aT PSC 
[sa _[aroo PFIO_[16001——~* aoe PSD 
[5 [oro Pr2 [Doo NF___[270s PSE 
[96 [2700 PP5_—_‘[sB00 8 ——~—~* aos PS 
a 
[ss [5600 PFun——‘[1H002———~«( DED NF 
[so [6500 Ins —~*([45000——~—~S~* DBO NF 
fio. [aro Pre _—‘[aso0 9 —SS~d Owe 
fio [4700 PFO ——~*['96006———~S~*siSaSd 
fia [st00 PFID_‘[26008——~—~*iSOe ed 
[ios [eDo0 Del [aon ———SS—~id ua Del Sd 
fos [7B00-——SS~d Ba SSSC~i BCS 
[106 | 7G00 Right Tab [7021 Right Tab [700s ————*d 
[108 [7900 Enter [7021 Enter [7008 


[500 Pri2__| 5Fo0 PFea__——~(|DEOONF_——*d 


Figure A-4 (Part 3 of 3). Default Scan Codes for IBM Enhanced PC 
Keyboard (MFI Mode) 


e 
0 
1 
2 
3 
4 
5 
6 
8 
0 
2 
3 
4 
5 
6 
7 
8 
9 
0 
1 
2 
3 
4 
5 


K 
91 
92 
93 
| 95 
97 
10 
10 
10 
10 
10 
10 
10 
10 
11 
11 
11 
11 
11 
11 
11 
Lt 
11 
12 
12 
12 
12 
12 
12 


Scan Code Tables 


Default Scan Codes for the PC XT Keyboard (PC Mode) 


2804 


Figure A-5 (Part 1 of 3). Default Scan Codes for IBM PC XT Keyboard 
(PC Mode) 


Key 
7 
10 
ia 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
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Scan Code Tables 


A-20 


i 


Lowercase 


3B00 j 


Figure A-5 (Part 2 of 3). Default Scan Codes for IBM PC XT Keyboard 
(PC Mode) 


Key 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
AT 
48 
49 
50 
51 
52 
53 
54 
55 
56 
57 
58 
59 
61 
62 
63 
64. 
65 
67 
70 
71 
72 


Scan Code Tables 


7D00 Page Up 7D21 Keypad 9 7D04 
7B00 - 7B21 - 7B04 


Cursor 


7200 Down 7221 Keypad 2 7204 
Cursor 


7A00 PgDn 7A21 Keypad 3 
7000 Insert 7021 Keypad 0 7004 
7100 Delete 


Figure A-5 (Part 3 of 3). Default Scan Codes for IBM PC XT Keyboard 
(PC Mode) 
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Scan Code Tables 


Default Scan Codes for the IBM PC XT Keyboard (MFI 


Mode) 


A-22 


Note: MFI = host/notepad. 


Figure A-6 (Part 1 of 3). Default Scan Codes for IBM PC XT Keyboard 
(MFI Mode) 


Key 
7 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 


Scan Code Tables 


[8 [Foo Pri0 | 4000 Pr20 [1100 Reset 
[eo [7700 Num Lock [0504 SysRq [0100 Enlarge 


Figure A-6 (Part 2 of 3). Default Scan Codes for IBM PC XT Keyboard 
(MFI Mode) 


Key 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 
48 . 
49 
50 
51 
52 
53 
54 
55 
56 
57 
58 
59 
61 
62 
63 
64 
65 
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Scan Code Tables 


Lowercase Alternate Case 
6C04 | 


6100 Left Cursor 6B21 Keypad 4 6104 Fast Left 
Cursor 


Cursor Cursor 


6000 Down 7221 Keypad 2 5604 UndSec 

Cursor 

6F00 PA3 7A21 Keypad 3 5E04 Ex 
Highlight 


6500 Insert 7021 Keypad 0 0804 DocMd 
6D00 Delete 6D04_ WdDel 


Note: NF (no function) means no function has been assigned to the specified key location. 


Figure A-6 (Part 3 of 3). Default Scan Codes for IBM PC XT Keyboard 
(MFI Mode) 


A-24 


Scan Code Tables 


Default Scan Codes for the IBM Personal Computer AT 
Keyboard (PC Mode) 


1 
1 
19 2400 e 2491 E 
20 2D00 r 2D21 R 
21 2C00 t 2C21 T 
22 3500. y 3521 Y 
23 3C00 u 3C21_U 
24 4300 i 4321 1 
25 4400 o 4421 O 
26 4D00 p 4D21 P 
27 5400 [ 5421 { 
28 5300 | 5321 } 
30 0900 Ctrl 0921 Ctrl 
31 1C00 a 1C21 A 
32 1B00 s 1B21 § 
33 2300 d 2321 D 
34 2B00 f 2B21 F 


Figure A-7 (Part 1 of 3). Default Scan Codes for IBM Personal Computer 
AT Keyboard (PC Mode) 


10 
11 
12 
3 
4 
5 
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Scan Code Tables 


A-26 


Alternate Case 
5900 Right Shift 5904 Right Shift 


Figure A-7 (Part 2 of 3). Default Scan Codes for IBM Personal Computer 
AT Keyboard (PC Mode) 


Key 
35 
36 
37 
38 
39 
40 
41 
43 
44 
46 
47 
48 
49 
50 
51 
52 
53 
54 
55 
57 
58 
61 
64 
65 
67 


70 
71 
72 
73 
74 
91 
92 
93 


Sean Code Tables 


7200 Down 7221 Keypad 2 7204 
Cursor 


7000 Insert 7021 Keypad 0 
7E00 ScrLk 1104 Quit 0321 ChScr 
7D00 PgUp 7D21 Keypad 9 


Cursor 


Note: NF (no function) means no function has been assigned to the specified key location. 


Key 
95 
97 
100 
101 
102 
103 
104 
105 
106 
107 
108 


Figure A-7 (Part 3 of 3). Default Scan Codes for IBM Personal Computer 
AT Keyboard (PC Mode) 
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Scan Code Tables 


Default Scan Codes for the IBM Personal Computer AT 
Keyboard (MFI Mode) 


A-28 


Alternate Case 


0E00 ° 0E21 | 0K04 


Figure A-8 (Part 1 of 3). Default Scan Codes for IBM Personal Computer 
Keyboard (MFI Mode) 


2 
2 
2 
2 
2 
2 
2 
2 
2 


3 


7 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
3 
3 
3 


0 
1 
2 
3 
4 
5 
6 
7 
8 
9 
0 
1 
2 
3 
4 
5 
6 
7 
8 
0 
1 
2 
3 
4 


3 


Scan Code Tables 


DEOO NF 


6100 Left Cursor 6B21 Keypad 4 6B04 Fast Cursor 
Left 


Figure A-8 (Part 2 of 3). Default Scan Codes for IBM Personal Computer 
Keyboard (MFI Mode) 


Key 
35 
36 
37 
38 
39 
40 
41 
43 
44 
46 
47 
48 
49 
50 
51 
52 
53 
54 
55 
57 
58 
61 
64 
65 
67 
70 
71 
12 
73 
74 
91 
92 
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Scan Code Tables 


A-30 


6000 Down 7221 Keypad 2 5604 UndSe 
Cursor 


[OB 
[ee [e500 tnsort | Toa Keypad ose Dood 
Cursor 


Note: NF (no function) means no function has been assigned to the specified key location. 


Figure A-8 (Part 3 of 3). Default Scan Codes for IBM Personal Computer 
Keyboard (MFI Mode) 


ASCII Tables 


ASCII Characters Common to All Countries 


ASCII Code PC and Host/Notepad 

(hex) (dec) Character 

2082 
Ea ee ee 0 


2521 Z 


eo Tar 

fo vali 

3 

| vai 

| vali 
PS eae oe oe Se 
aes | eel 
oo Select screen 
6 Select screen | 
so Select screen | 
oo Select screen | 
eee el 
ae | ee 
ee erates 1. Dee 
Bo Select window | 
DO Select window | 


Figure A-9 (Part 1 of 3). Valid ASCII Characters Common to All 
Countries 


WsCtrl Function 
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ASCII Tables 


A-32 


PC and Host/Notepad | 
Character 


WsCtrl Function 


Select window 
Select window 
Select window 


ASCII Code 
(hex) (dec) 
46 70 


48 72 


4B 75 


4D 77 
4E 78 


Select window 


Select window 


Select window 


51 81 
Select window 


52 82 


Figure A-9 (Part 2 of 3). Valid ASCII Characters Common to All 
Countries 


62 98 


joy) 
me | Co 
me 1 CO 
2 
© 


| i : i 
CO; ~1] o>] Or 
ee ed ee 
Clholro;lo co 
mem} OO} D ] re 


for) 
> 
—_ 
© 


or) 
ite) 
om 
j=) 
oO 


6 


oP) 
a) 
he 
>) 
ve) 


6E = 110 


ASCII Tables 


Fa Sad 
(hex) (dec) Character WsCtrl Function 
r 
oa 
TA 1a 


Figure A-9 (Part 3 of 3). Valid ASCII Characters Common to All 
Countries 


6F 111 
70 112 
71 113 
72 114 
73 115 
74 116 
75 117 
76 118 
77 119 
78 120 
79 121 
7A = 122 
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ASCII Tables 


ASCIT Mnemonics Common to All Countries 


WsCtrl Function 


as 


Figure A-10 (Part 1 of 3). Valid ASCIT Mnemonics Common to All Countries 


A-34 


ASCII Tables 


(a rete [REE rts 
Mnemonic PC Function Function WsCtrl Function 


@h 
3 


Tak 


Figure A-10 (Part 2 of 3). Valid ASCII Mnemonics Common to All Countries 
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ASCII Tables 


[a 
Mnemonic PC Function Function WsCtrl Function 
@0 


@A@E PSE (DFT only) 
@A@e 3 PSF (DFT only) 


@A@7 Invalid Reset program symbols Invalid 
(DFT only) 

@A@9 Invalid Reverse video (DFT and Invalid 
notepad) 


Hilite (DFT and notepad 

@A@b Invalid Underscore (DFT and Invalid 
notepad) 

@A@c Invalid Reset reverse video, etc. Invalid 
(DFT and notepad) 

@A@d Invalid Red (DFT and notepad) 
Doc mode (CUT) 

@A@e Invalid Pink (DFT and notepad) Pink 
Wrap (CUT) 

@A@f Invalid Green (DFT and notepad) | Green 
Chg format (CUT) 

@A@g Invalid Yellow (DFT and Yellow 
notepad) 


GAGE Blue (DFT and notepad) 
Turg (DFT and notepad) 


@AQ@) Invalid White (DFT and White 
notepad) 


@AGE Black (DFT and notepad 


@AQ@I Invalid Reset host colors (DFT Invalid 
and notepad) . 


[@A@m [Invalid [Gr Pasition (CUD 


@/ Queue full, Queue full, keystrokes Queue full, 
keystrokes lost lost keystrokes lost 


Figure A-10 (Part 3 of 3). Valid ASCII Mnemonics Common to All Countries 
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ASCII Tables 


Additional ASCII Characters Used by U.S. English 


ASCII Code Character 
mes) a Description aan orcas 


: 


Figure A-11. Additional ASCII Characters Used by U.S. English 
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Introduction 


Introduction 


This appendix describes the destination/origin structured field formats and 
protocol used by your IBM 3270 PC application program to move data 
between a host session and the personal computer session (using the host 
interactive services). Structure types accepted by the 3270 Workstation 
Program are designated Open (X‘D000’), Close (X‘D041’), Set Cursor 
(X‘D045’), Get (X‘D046’), and Insert and Insert Data (X‘D047’). No other 
types are allowed when using the 3270 PC application program interface. 


The 3270 data stream was defined for use between a host application 
program and a single display; it allows support of a 3270 data stream work 
station. A 3270 data stream work station consists of a 3270 data stream 
display and one or more personal computer (PC) application programs. A 
PC application program does not accept the usual 3270 data stream (for 
example, 3270 commands, orders, and so forth). However, the 3270 data 
stream is used to carry the data streams associated with the PC application 
programs. The data to and from PC application programs must be in the 
form of structured fields. 


The 3270 Outbound Data Stream 


The 3270 outbound data stream is a data stream sent from the host to the 
3270 Personal Computer. The 3270 outbound data stream containing 
structured fields begins with a Write Structured Field (WSF) command 
X‘F3’ or X‘11’. Multiple structured fields can be sent with one WSF 
command. 


WSF Structured | Structured Structured 
Field 1 Field 2 Field n 


The 3270 Inbound Data Stream 


The 3270 inbound data stream is a data stream sent from the 3270 Personal 
Computer to the host. The 3270 inbound data stream containing structured 
fields begins with an attention identifier (AID): 


AID Structured Field 


The structures used by the 3270 Personal Computer follow the 3270 data 
stream format. The maximum number of bytes that can be sent in one 
transmission in either direction is 3.5K bytes (K equals 1024). (For more 
information on structured fields, refer to the IBM 3274 Control Unit 
Description and Programmer’s Guide.) 
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Verifying Interface Is Operational 


Verifying That the IBM 3270 Personal Computer 
Interface Is Operational 


Prior to a request from the host application to the 3270 Personal Computer, 
the host application must verify (with the control unit) that the 3270 
Personal Computer interface is operational. This is done with a Read 
Partition Query structured field. The workstation program then returns a 
specific Query Reply back to the host. 


The Read Partition Query Structured Field 


The read partition query and query reply structures verify that a path 
exists between the host application and the 3270 PC application. The host 
application inquires about the 3270 PC application. 


Figure B-1 shows the format of the read partition query structured field. 


0,1 X‘0005’ Length of structured field in 
bytes 
2 


ie kr | Read partition ID code 
3 X‘FF’ Partition identifier physical 
terminal: query operation 


4 Type Query (used in both implicit 
X‘02’ partition and explicit 


partitioned states) 


Figure B-1. Read Partition Query Structured Field Format 


The Query Reply Structured Field 
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Figure B-2 shows the format of the query reply structured field. The field 
is returned only when the PC application is loaded and active. 


The maximum bytes per transmission allowed on inbound and outbound 
transmissions is the 3.5K-byte length restriction enforced by the control 
unit on structures to and from the 3270 Personal Computer. (Refer to the 
IBM 3274 Control Unit Description and Programmer’s Guide for more 
information.) 


Verifying Interface Is Operational 


Offset__| Length 
fot byte Not used 
1 byte Uedethicrawuctie 
Query Reply 
1 byte Query Reply type 
Reserved flags 
1 byte Structured Field Exchange 
6, 7 2 bytes 
allowed in an inbound 
transmission 
2 bytes {| Maximum of Maximum number of bytes 
X‘0E00’ allowed in an outbound 
transmission 


10 1 byte Must be X‘OF’ Identifies the next two bytes as 
being the destination/origin ID. 
11 1 word Must be zero Destination/origin ID supplied 
by the 3270 Workstation 
Program. 


APLNME Application name (in EBCDIC) 


Figure B-2. Query Reply Structured Field Format 


Meaning 


Maximum of 
X‘OE00’ 


Maximum number of bytes 


When the 3270 Personal Computer powers off, the interface to the control 
unit is disabled. If a host application attempts to exchange data with a PC 
application, the control unit returns a Data Stream Error-OP CHECK. 
(Refer to the component description card in your Guide to Operations for 
more information about OP CHECK.) 


The presentation space associated with a PC application program is 
independent of the display presentation space. Data directed to a PC 
application program does not alter the display presentation space, and data 
directed to the display presentation space does not alter the presentation 
space associated with a PC application program. 


A different type of Query Reply is defined for each different IBM data 
stream used by PC application programs. The Query Reply identifies the 
IBM data stream supported. 


The display is the default destination or origin if the data destination or 
origin is not explicitly identified by a destination/origin structured field. 
Data of a type not supported that is directed to the display or a PC 
application program will be rejected. 


At the start of each outbound transmission the destination is the display, 
and at the start of each inbound transmission the origin is the display. The 
destination/origin remains the display unless changed by a 
destination/origin structured field. Once a destination/origin structured 
field has established the destination/origin of the data, that 
destination/origin applies for all structured fields that follow until the end 
of the transmission or until changed by a subsequent destination/origin 
structured field. 
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Input Control 


Query Reply 


Input Control 
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The PC application program Query Reply is sent in reply to either a Query 
or Query List. 


Return of the AUXDA Query Reply indicates a 3270 Data Stream Work 
Station implementation (that is, support of the destination/origin structured 
field and one or more PC application programs). The AUXDA Query Reply 
is returned in reply to either a Query List (= AUXDA or All) or a Query. 


The workstation program inserts the Destination/Origin Identification 
(DOID) value into the Query Reply for the Destination/Origin structured 
field in individual PC application programs. 


A Query or Query List directed to a PC application program instead of to 
the display will be rejected. 


A separate Query Reply must be returned for each PC application program 
supported. For example, if two identical PC application programs were 
supported, a Query Reply would be returned for each. The DOID reported 
would be different for each. 


The host application controls when the PC application is permitted to send 
in data. The control is achieved with the INCTRL (input control) flag in 
the destination/origin structured field. The INCTRL flag has meaning only 
on outbound transmissions (to the 3270 PC) and is ignored on inbound 
transmissions. When the destination/origin structured field is directed to 
the display (ID = X‘0000’), the INCTRL flag provides a global control. 


The default (for example, Power-On-Reset from the control unit) is 
input-disabled. Once input is enabled, it remains enabled until disabled by 


one of the following: 


e A destination/origin structured field with the INCTRL flag set to B‘10’ 
(input disable) is sent outbound to the PC application. 


e A destination/origin structured field with the INCTRL flag set to B‘10’ 
(global input disable) is sent outbound to the display. 


e An Erase Write or Erase Write Alternate command with the Write 
control character set to reset is sent outbound. 


e Aclear local function (for example, the Clear key is pressed). 
e A Power-On-Reset. 


e The 3270 PC receives a Bind (SNA only). 


PC Application Program 


Receiving a destination/origin structured field from the host application 
with INCTRL set to B‘01’ will not cause a change in the input 
enable/disable state of the PC application. Also, if the INCTRL flag value 
is the same as the existing input enable/disable state, the state is 
unchanged. For example, if the input enable/disable state is input-enabled, 
receiving a destination/origin structured field with INCTRL set to B‘00’ 
(input enable) will be accepted and the input enable/disable state will 
remain enabled. 


Note: There is one exception where input may be sent without being enabled. 
An exception condition structured field, reporting unavailability of the 
PC application, may be sent in reply to a destination/origin structured 
field sequence attempting to use it. 


PC Application Program and Display Interaction 


The PC application programs must conform to the read operations described 
in the IBM 3270 Information Display System Data Stream Programmer’s 
Reference, except where otherwise noted here. 


When data is read in from a PC application, the rules or states for Read 
Retry and Read Acknowledgment apply. For example, once a transmission 
is sent from a PC application, additional data from that application cannot 
be sent inbound until a Read Acknowledgment is received. If the data from 
a PC application is transmitted in multiple transmissions, each 
transmission requires an acknowledgment. An inbound transmission may 
contain data from the display and/or data from one or more PC 
applications. When display data is sent in the same transmission as PC 
application data, the Inbound 3270DS structured field must be used for the 
display data. An inbound transmission containing data from PC 
applications must start with an AID of X‘88’, which indicates structured 
fields follow. The same conditions that acknowledge a Query Reply will 
acknowledge an inbound transmission from a PC application. 


An outbound transmission to a PC application constitutes a read 
acknowledgment per the description for outbound display transmissions. 
The fact that the transmission is to a PC application adds no additional 
acknowledgment function. For example, a transmission to a PC application 
would acknowledge an outstanding Query Reply transmission because the 
transmission contained a WSF. As another example, in the SNA 
environment a transmission to a PC application would constitute an 
acknowledgment to an outstanding enter transmission only if the 
transmission put the work station in a send or contention state. 


Only one display-type read may occur in an outbound transmission, and 
when in structured field form, it must be the last structured field in the 
transmission. A display-type read is defined as any of the following: 


e A query or query list structured field 


e A read partition structured field 
e A Read Buffer, Read Modified, or Read Modified All command. 
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Exception Handling 


In an outbound transmission, data to a PC application can initiate inbound 
data from that application. Inbound data can be initiated from multiple PC 
applications by a single outbound transmission containing multiple 
destination/origin structured fields. Inbound data from one or more PC 
applications can be initiated in an outbound transmission that also 
contains a display-type read. When this occurs, the display-type read is 
executed first. 


A display-type read always takes priority over pending inbound data from a 
PC application. A display operator enter action is considered a display-type 
read. If inbound data is pending from one or more PC applications, an 
operator enter action will take priority and use the next available inbound 
transmission. 


When the data from a PC application must be sent in multiple 
transmissions (for example, a transmission size limit imposed for certain 
data), each inbound transmission is treated like an Enter, to the extent that 
sending of the data is initiated by the application. A host Read 
Acknowledgment is required prior to sending the next part of the data. 
Therefore, data from a PC application that is sent in multiple transmissions 
could have some interspersed display transmissions. Also, the display 
operator is not “locked out” as a result of a PC application condition (for 
example, power off, diskette removed, and so forth). 


Exception Handling 


An exception condition in a PC application does not cause the session 
between the host and the 3270DS work station to be terminated. That is, a 
PC application program exception condition must not cause a negative 
response. Exception conditions must be reported at the application level. 


In general, the exception handling is defined by the data stream used by the 
PC application. ; 


Some exception conditions are handled within the 3270DS. For example, if 
the PC application is not available (such as when power is off or processing 
code is not resident), the unavailability is reported by returning a 
destination/origin structured field followed by an exception condition 
structured field with the code field set to X‘0801’ (resource not available). 
Another example is where the host exceeds the transmission size specified 
in a PC application Query Reply. In this case, the code field is set to 
X‘084C’ (permanent insufficient resource). 


Structured Fields 


Structured Fields 


Destination/Origin 


The destination/origin structured field is used to designate the destination 
or origin of the structured fields that follow in the data stream. 


Format 


a X‘0008’ Length of this structure 
a X‘OF02’ Destination/origin 


Flags: 


INCTRL 
B‘00’ 


Input Control 
Enable input 


BOV’ No change 
B‘10’ Disable input 
Bill’ Reserved 


RES Reserved — must be zeros 


6, 7 ID Identifies the destination or origin 
of the structured fields that follow 
in the data stream 


Flags: INCTRL applies only on outbound transmissions (to the PC 
application). The INCTRL flag is ignored on inbound retransmissions. 


1. B‘00’ — The PC application is allowed to send data. If the PC 
application is already enabled, it will remain enabled. 


2. B‘01’ — A change does not occur in the enabled/disabled status. 


3. B‘10’ — The PC application is not permitted to send data until 
subsequently enabled by a destination/origin structured field with 
INCTRL flag = B‘01’. If the PC application is already disabled, the 
INCTRL flag = B‘10’ will cause no change. 


If a destination/origin structured field is directed to the base display (ID = 
X‘0000’), the INCTRL flag applies on a global basis. That is, all the 
supported PC applications are enabled, disabled, or unchanged as a group. 


Note: There is one case where a PC application may send input without 
being enabled. An exception condition structured field, reporting 
unavailability of the PC application, may be sent in reply to a 
destination/origin structured field sequence attempting to use the PC 
application. 
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Structured Fields 


ID; The valid values for the ID are: 

e X‘0000’ (permanently assigned to the primary display) 

e All ID values returned in the Query Reply(s) for PC applications. 

All other values are invalid and are rejected. 

Operation: The function of the destination/origin structured field is to 
identify the destination or origin of the structured fields in a single-session 
multidevice (work station) implementation. 

Outbound (from the host) the ID identifies the destination of the structured 
fields that follow. Inbound (to the host) the ID identifies the origin of the 
structured fields that follow. 


At the beginning of the transmission, the destination/origin is the default 
(primary display). 


Once a destination/origin structured field establishes the destination/origin, 
it applies until either another destination/origin structured field establishes 
a new destination/origin or a new transmission starts. 


Exception Condition 


B-10 


The exception condition structured field allows the reporting of exception 
information at the application level. 


Format 


Peng ed ald 
[2.8 | __[X0F227 | Exception condition —_———*? 
[___]rm | Partition identifier 
[——Ttags [Reserved — must be eros 


Length of parameter 


X‘OL’ Application program exception 
condition 
EXCODE Exception code 


X‘DO’ Structured Fields, Host to 3270 PC 


PID: The PID should be set to X‘FF’. 


EXCODE:;: This defines the specific direct-accessed PC application 
exception condition. 


Code Meaning 


0801 Resource not available. The required processing code is not 
resident. 


084B § Temporary insufficient resource. The application did not provide a 
buffer. 


084C Permanent insufficient resource. The host sent more than X‘0E00’ 
bytes of data. 


1003 Invalid function code 


Operation: The exception condition structured field is allowed to carry 
only one exception condition. 


When used for reporting an exception condition for a direct-accessed PC 
application, the exception condition structured field must be preceded by a 
destination/origin structured field. 


X‘DO’ Structured Fields for Sending Data from the Host 
to the 3270 Personal Computer 


The following structures describe the requests sent by the host and the 
responses sent by the 3270 PC application through the 3270 PC Application 
Program Interface. 


The data part of the Insert and Insert Data X‘DO’ structured fields is defined 
by the host application file formats for the 3270 Personal Computer. All 
numbers given in the request and response formats are hexadecimal values. 


Transferring data from the host to the 3270 Personal Computer is 
accomplished by the following sequence of X‘DO’ structured fields: 


1. The Open X‘DO’ Structured Field (X‘D000’) 


The host application sends an Open X‘D0’ structured field request to the 
3270 PC application program. The Open request contains the ASCII 
format name of the data to be sent and the ASCII file specification of 
the file to be created on the 3270 Personal Computer. The application 
program must check the host request for validity, and send a X‘D0’ 
structured field response to the host indicating whether the Open 
request was successful or unsuccessful. 
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X‘DO’ Structured Fields, Host to 3270 PC 


2. The Insert and Insert Data X‘DO’ Structured Fields (X‘D047’) 


The host application sends the Insert and Insert Data X‘DO’ structured 
field requests to the application program. These two requests are 
always sent in the same transmission. The Insert request indicates to 
the application program that an insert operation is to be done on the 
opened file. The Insert Data request contains both the length of the 
data to be inserted into the opened file and the data itself. The 
application program must check the host requests for validity, and send 
a X‘DO’structured field response indicating whether the Insert and 
Insert Data requests were successful or unsuccessful. The host program 
continues to send the Insert and Insert Data requests to the 3270 PC 
application program until all the data is sent. 


3. The Close X‘DO’ Structured Field (X‘D041’) 


The host application sends a Close X‘D0’ structured field request to the 
3270 PC application program when all the data has been sent. The 
application program must check the host request for validity, and send 
a X‘D0’ structured field response to the host indicating whether the 
Close request was successful. 


The Open X‘D0’ Structured Field 


The Open X‘DO’ structured field request forms a logical connection between 
an application on the host system and a file on the 3270 Personal Computer 
system. Once the connection has been made, requests and data may flow 
from the host to the 3270 Personal Computer. 


Format of the Host Open Request 


The buffer sent by the host to the 3270 PC application program for the Open 
X‘DO’ structured field request must be formatted as follows: 


Byte (Decimal) Contents (Hex) 


0,1 LL, a 2-byte length field (the length of the 
transmission, including LL) 


2 L1, a 1-byte length field (2 + length of format 


NAME) 


9 
30 through n NAME, a variable-length field containing the 
format name (in ASCII) 
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X‘DO’ Structured Fields, Host to 3270 PC 


Byte (Decimal) Contents (Hex) 
03 


not 2 L2, a 1-byte length field (2 + length of the 3270 
Personal Computer file specification) 

n+ 3throughm | FILSPEC, a variable-length field containing the 
3270 Personal Computer file specification in ASCII 


Note: The host Open request must be coded as shown above. 


When the Workstation Program receives the request from the host, it puts 
it into the buffer defined by the DEF-BUF service. The 3270 PC application 


uses the READ-SF and GET-COMP services to receive the data in the 
following format: 

Byte (Decimal) Contents (Hex) 

Ze xx xx, a 2-byte length field containing the length 
of the outbound transmission received from the 
host, excluding the buffer header, which is 8 bytes 
first. 

4 through 7 00 00 CO 00 
LL, a 2-byte length field (the length of the 
transmission, including LL) 

19 through 27 OA OA 00 00 00 00 11 01 01 

28 through 34 00 50 05 52 03 FO 08 

LO, a 1-byte length field (8 + length of format 
28 

37 Ll, a 1-byte length field (2 + length of format 

NAME) 
03 

n+ 2 L2, a 1-byte length field (2 + length of the 3270 
Personal Computer file specification) 

n+ 38throughm | FILSPEC, a variable-length field containing the 
3270 Personal Computer file specification in ASCII 


long. This is in the PC format with low-order byte 
10 through 18 DO 00 12 01 06 01 01 04 08 
NAME) 
38 through n NAME, a variable-length field containing the 
format name (in ASCII) 
Bytes 0 through 7 are the buffer header. 
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X‘DO’ Structured Fields, Host to 3270 PC 


Format of the Successful Transmission Response 


To indicate a successful transmission of the Open X‘DO’ structured field 
request, the 3270 PC application uses the WRITE-SF service to send a 
message to the host in the following format: 


Byte (Decimal) | Contents (Hex) 
0 through 7 00 00 05 00 00 00 00 00 
8 through 12 00 05 DO 00 09 


Bytes 0 through 7 are the buffer header. Bytes 2 and 3 are the length of the 
structured field message that begins in byte 8. The successful transmission 
response must be coded as shown above. 


When the Workstation Program receives the response from the 3270 PC 
application program, it sends it to the host in the following format: 


Byte (Decimal) | Contents (Hex) 
0 through 4 00 05 DO 00 09 


Format of the Unsuccessful Transmission Response 
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To indicate an.unsuccessful transmission of the Open X‘DO’ structured field 
request, the 3270 PC application program uses the WRITE-SF service to 
send a message to the host in the following format: 


Byte Decimal) 
0 through 7 00 00 09 00 00 00 00 00 
8 through 16 00 09 DO 00 08 69 04 xx 00 


Bytes 0 through 7 are the buffer header. Bytes 2 and 3 are the length of the 
structured field message that begins in byte 8. The unsuccessful 
transmission response must be coded as shown above. 


xx is one of the following: 


01 Open failed exception 

02 Arrival sequence not allowed 
1A File name invalid 

1B File not found 

1C_ File size invalid 

20 Function/open error 

2A Path not found 

5D Unsupported type 


X‘D0O’ Structured Fields, Host to 3270 PC 


60 Command sequence error 

62 Parameter is missing 

63 Parameter not supported 

65 Parameter value not supported 
71 Invalid format 


When the Workstation Program receives the response from the 3270 PC 
application program, it sends it to the host in the following format: 


Byte (Decimal) | Contents (Hex) 
0 through 8 00 09 DO 00 08 69 04 xx 00 


xx is one of the values listed above. 


The Insert and Insert Data X‘D0’ Structured Fields 


The Insert and Insert Data X‘DO’ structured field requests are always sent 
in the same transmission. The Insert X‘DO’ structured field request 
indicates that an insert operation is to be performed on the opened file. 
The Insert Data X‘DO’ structured field request contains both the length of 
the data to be inserted into the opened file and the data itself. 


Format of the Host Insert and Insert Data Requests 


The buffer sent by the host to the 3270 PC application program for the 
Insert and Insert Data X‘DO’ structured field requests must be formatted as 
follows: 


transmission, from LL to the end of the data) 


LD, a 2-byte length field (5 + length of the data) 
DATA, the data being sent 


Note: The host Insert and Insert Data requests must be coded as shown 
above. 
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X‘DO’ Structured Fields, Host to 3270 PC 


When the Workstation Program receives the request from the host, it puts 
it into the buffer defined by the DEF-BUF service. The 3270 PC application 


program uses the READ-SF and GET-COMP services to receive the data in 
the following format: 
Byte (Decimal) | Contents (Hex) 
00 00 
2, 3 ‘| xx xx, a 2-byte length field containing the length of 
the outbound transmission received from the host 
excluding the buffer header, which is 8 bytes long. 
This is in PC format with low-order byte first. 
4 through 7 00 00 CO 00 
8 through 17 00 0A DO 47 11 01 05 00 80 00 
18, 19 LL, a 2-byte length field (the length of the 
transmission, including LL) 
20 through 25 DO 47 04 CO 80 61 
26, 27 LD, a 2-byte length field (5 + length of the data) 
28 through n DATA, the data being sent 
Bytes 0 through 7 are the buffer header. 


Format of the Successful Transmission Response 
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To indicate a successful transmission of the Insert and Insert Data X‘D0’ 
structured field requests, the 3270 PC application program uses the 
WRITE-SF service to send a message to the host in the following format: 


Byte (Decimal) | Contents (Hex) 
0 through 7 00 00 OB 00 00 00 00 00 
8 through 14 00 OB DO 47 05 63 06 


15 through 18 DATBLK, a 4-byte field containing the data block 
number received. For the first data block, 
DATBLK = 00 00 00 01. 


Bytes 0 through 7 are the buffer header. Bytes 2 and 3 are the length of the 
structured field message that begins in byte 8. The successful transmission 
response must be coded as shown above. 


X‘DO’ Structured Fields, Host to 3270 PC 


When the Workstation Program receives the response from the 3270 PC 
application program, it sends it to the host in the following format: 


Byte (Decimal) | Contents (Hex) 
0 through 6 00 OB DO 47 05 63 06 


7 through 10 DATBLK, a 4-byte field containing the data block 
number received. For the first data block, 
DATBLK = 00 00 00 01. 


Format of the Unsuccessful Transmission Response 


To indicate an unsuccessful transmission of the Insert and Insert Data 
X‘DO’ structured field requests, the 3270 PC application program uses the 
WRITE-SF service to send a message to the host in the following format: 


Byte (Decimal) .| Contents (Hex) 
0 through 7 00 00 09 00 00 00 00 00 
8 through 16 00 09 DO 47 08 69 04 xx 00 


Bytes 0 through 7 are the buffer header. Bytes 2 and 3 are the length of the 
structured field message that begins in byte 8. The unsuccessful 
transmission response must be coded as shown above. 


xx is one of the following: 


02 Arrival sequence not allowed 
3E Operation not authorized 

47 Record not added, storage limit 
5D Unsupported type 

60 Command syntax error 

62 Parameter is missing 

63 Parameter not supported 

65. Parameter value not supported 
6E Data element missing 

70 Record length = 0 

71 Invalid flag value 


When the Workstation Program receives the response from the 3270 PC 
application program, it sends it to the host in the following format: 


Byte (Decimal) | Contents (Hex) 
0 through 8 00 09 DO 47 08 69 04 xx 00 


xx is one of the values listed above. 
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X‘DO’ Structured Fields, Host to 3270 PC 


The Close X‘D0’ Structured Field 


The Close X‘DO’ structured field request performs the logical termination of 
a connection between a file on the host system and a previously opened file 
on the personal computer system. 


Format of the Host Close Request 


The buffer sent by the host to the 3270 PC application program for the 
Close X‘DO’ structured field request must be formatted as follows: 


Byte (Decimal) | Contents (Hex) 


Note: The host close request must be coded as shown above. 


When the Workstation Program receives the request from the host, it puts 
it into the buffer defined by the DEF-BUF service. The 3270 PC application 
program uses the READ-SF and GET-COMP services to receive the data in 
the following format: 


Byte (Decimal) | Contents (Hex) 
0 through 7 00 00 05 00 00 00 CO 00 
8 through 12 00 05 DO 41 12 


Bytes 0 through 7 are the buffer header. 


Format of the Successful Transmission Response 
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To indicate a successful transmission of the Close X‘DO’ structured field 
request, the 3270 PC application program uses the WRITE-SF service to 
send a message to the host in the following format: 


Byte (Decimal) | Contents (Hex) 
0 through 7 00 00 05 00 00 00 00 00 
8 through 12 00 05 DO 41 09 


Bytes 0 through 7 are the buffer header. Bytes 2 and 3 are the length of the 
structured field message that begins in byte 8. The successful transmission 
response must be coded as shown above. 


X‘DO’ Structured Fields, Host to 3270 PC 


When the Workstation Program receives the response from the 3270 PC 
application program, it sends it to the host in the following format: 


Byte (Decimal) | Contents (Hex) 
0 through 4 00 05 DO 41 09 


Format of the Unsuccessful Transmission Response 


To indicate an unsuccessful transmission of the Close X‘DO’ structured field 
request, the 3270 PC application program uses the WRITE-SF service to 
send a message to the host in the following format: 


Byte (Decimal) | Contents (Hex) 
0 through 7 00 00 09 00 00 00 00 00 
8 through 16 00 09 DO 41 08 69 04 xx 00 


Bytes 0 through 7 are the buffer header. Bytes 2 and 3 are the length of the 
structured field message that begins in byte 8. The unsuccessful 
transmission response must be coded as shown above. 


xx is one of the following: 
03 Close of an unopened file 
5D Unsupported type 


60 Command syntax error 
71 Invalid format 


When the Workstation Program receives the response from the 3270 PC 
application program, it sends it to the host in the following format: 


Byte (Decimal) { Contents (Hex) 
0 through 8 00 09 DO 41 08 69 04 xx 00 


xx is one of the values listed above. 
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X‘DO’ Structured Fields, PC to Host 


X‘D0O’ Structured Fields for Sending Data from Personal 
Computer to Host 
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The following structures detail the requests sent by the host and the 
responses sent by the 3270 PC application program through the 3270 
Personal Computer Application Program Interface. 


The data part of the Set Cursor and Get X‘D0’ structured fields is defined by 
the host application file formats for the 3270 Personal Computer. All 
numbers given in the request and response formats are hexadecimal values. 


Data is transferred from the 3270 Personal Computer to the host by the 
following sequence of X‘D0’ structured fields: 


1. 


The Open X‘D0’ Structured Field (X‘D000’) 


The host application sends an Open X‘D0’ structured field request to the 
3270 PC application program. The Open request contains the ASCII 
format name of the data to be sent and the ASCII file specification of 
the file to be sent to the host from the 3270 Personal Computer. The 
application program must check the host request for validity, and send 
a X‘D0O’ structured field response to the host indicating whether the 
Open request was successful or unsuccessful. 


The Set Cursor and Get X‘DO’ Structured Fields (X‘D045’ and X‘D046’) 


The host application sends the Set Cursor and Get X‘D0’ structured 
field requests to the application program. These two requests are 
always sent in the same transmission. The Set Cursor request sets the 
logical block pointer (cursor) of the opened file to the next data block to 
be sent. The Get request requests a block of data from the 3270 
Personal Computer. The PC application sends the specified data block 
of the opened file to the host. The application program must check the 
host requests for validity, and send a X‘D0O’structured field response 
indicating whether the Set Cursor and Get requests were successful or 
unsuccessful. The host program continues to send the Set Cursor and 
Get requests to the 3270 PC application program until all the data is 
sent. 


The Close X‘DO’ Structured Field (X‘D041’) 


The host application sends a Close X‘D0’ structured field request to the 
3270 PC application program when all the data has been sent. The 
application program must check the host request for validity, and send 
a X‘DO’ structured field response to the host indicating whether the 
Close request was successful. 


X‘DO’ Structured Fields, PC to Host 


The Open X‘D0O’ Structured Field 


The Open X‘DO’ structured field request forms a logical connection between 
an application on the host system and a file on the 3270 Personal Computer 
system. Once the connection has been made, requests may flow from the 
host to the 3270 Personal Computer, and data may flow back from the 3270 
Personal Computer to the host. 


Format of the Host Open Request 


The buffer sent by the host to the 3270 PC application program for the Open 
X‘DO’ structured field request must be formatted as follows: 


Byte (Decimal) Contents (Hex) 
0,1 LL, a 2-byte length field (the length of the 
transmission, including LL) 
DO 00 12 01 06 01 01 04 03 


11 through 19 0A 0A 00 01 00 00 00 00 01 
20 oe 26 00 50 05 52 03 FO 08 


LO, al- oe length field (4 + length of format 
5 eae Sees 


L1, a 1-byte length field (2 + length of Be 
NAME) 

30 through n NAME, a variable-length field containing the 
format name (in ASCII) 


Ne 2 = a 1-byte length field (2 + length of the 3270 
Personal Computer file specification) 

n+ 8throughm | FILSPEC, a variable-length field containing the 
3270 Personal Computer file specification (in 
ASCTI) 


Note: The host Open request must be coded as shown above. 
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X‘DO’ Structured Fields, PC to Host 


When the Workstation Program receives the request from the host, it puts 
it into the buffer defined by the DEF-BUF service. The 3270 PC application 
program uses the READ-SF and GET-COMP services to receive the data in 
the following format: 


Byte (Decimal) Contents (Hex) 
00-00 


2,3 xx xx, a 2-byte length field containing the length 
of the outbound transmission received from the 
host excluding the buffer header, which is 8 bytes 
long. This is in PC format with low-order byte 

4 through 7 00 00 CO 00 
LL, a 2-byte length field (the length of the 
transmission, including LL) 


10 through 18 DO 00 12 01 06 01 01 04 03 


28 through 34 00 50 05 52 03 FO 08 
35 


LO, a 1-byte length field (4 + length of format 
NAME) 


37 L1, a 1-byte length field (2 + length of format 
NAME) 

38 through n NAME, a variable-length field containing the 

format name (in ASCII) 


n+ 2 L2, a 1-byte length field (2 + length of the 3270 
Personal Computer file specification) 

n+ 8throughm | FILSPEC, a variable-length field containing the 
3270 Personal Computer file specification (in 
ASCID) 


Bytes 0 through 7 are the buffer header. 


Format of the Successful Transmission Response 
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To indicate a successful transmission of the Open X‘DO’ structured field 
request, the 3270 PC application program uses the WRITE-SF service to 
send a message to the host in the following format: 


Byte (Decimal) Contents (Hex) 


0 through 7 00 00 05 00 00 00 00 00 
8 through 12 00 05 DO 00 09 


Bytes 0 through 7 are the buffer header. Bytes 2 and 3 are the length of the 
structured field message that begins in byte 8. The successful transmission 
response must be coded as shown above. 


When the Workstation Program receives the response from the 3270 PC 
application program, it sends it to the host in the following format: 


X‘DO’ Structured Fields, PC to Host 


Byte (Decimal) | Contents (Hex) 
0 through 4 00 05 DO 00 09 


Format of the Unsuccessful Transmission Response 


To indicate an unsuccessful transmission of the Open X‘DO’ structured field 
request, the 3270 PC application program uses the WRITE-SF service to 
send a message to the host in the following format: 


Byte (Decimal) | Contents (Hex) 
0 through 7 00 00 09 00 00 00 00 00 
8 through 16 00 OB DO 00 08 69 04 xx 00 


Bytes 0 through 7 are the buffer header. Bytes 2 and 3 are the length of the 
structured field message that begins in byte 8. The unsuccessful 
transmission response must be coded as shown above. 


xx is one of the following: 


01 Open failed exception 

02 Arrival sequence not allowed 
1A File name invalid 

1B File not found 

1C_ File size invalid 

20 Function/open error 

2A Path not found 

5D Unsupported type 

60 Command syntax error 

62 Parameter is missing 

63 Parameter not supported 

65 Parameter value not supported 
71 Invalid format 


When the Workstation Program receives the response from the 3270 PC 
application program, it sends it to the host in the following format: 


Byte (Decimal) | Contents (Hex) 
0 through 8 00 09 DO 00 08 69 04 xx 00 


xx is one of the values listed above. 


The Set Cursor and Get X‘D0’ Structured Field 


The Set Cursor and Get X‘D0’ structured field requests are always sent in 
the same transmission. The Set Cursor X‘DO’ structured field request sets 
the logical block pointer (cursor) in the opened file to the next data block 
to be sent. The Get request requests a block of data from the 3270 Personal 
Computer. The PC application program sends the specified data block of 
the opened file to the host in its reply. 
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X‘DO’ Structured Fields, PC to Host. 


Format of the Host Set Cursor and Get Requests 


The buffer sent by the host to the 3270 PC application program for the Set 
Cursor and Get X‘DO’ structured field requests must be formatted as follows: 


Note: The host Set Cursor and Get requests must be coded as shown above. 


When the Workstation Program receives the request from the host, it puts 
it into the buffer defined by the DEF-BUF service. The 3270 PC application 
program uses the READ-SF and GET-COMP services to receive the data in 
the following format: 


Byte (Decimal) | Contents (Hex) 
00 00 
2,3 xx xx, a 2-byte length field containing 
the length of the outbound transmission 
received from the host excluding the 
buffer header, which is 8 bytes long. This 
is the PC format with low-order byte first. 
00 00 Co 00 
8 through 17 00 OF DO 45 11 01 05 00 06 00 
18 through 22 09 05 01 03 00 
23 through 31 00 09 DO 46 11 01 04 00 80 
Bytes 0 through 7 are the buffer header. 
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X‘DO’ Structured Fields, PC to Host 


Format of the Successful Transmission Response 


To indicate a successful transmission of the Set Cursor and Get X‘DO’ 
structured field requests, the 3270 PC application program uses the 
WRITE-SF service to send a message to the host in the following format: 

Byte (Decimal) | Contents (Hex) 

2,3 xx xx, a 2-byte length field containing the length of 

the data that begins in byte 8. This is the PC 
format with low-order byte first. 

00-00-00 00 
LL, a 2-byte length field (the length of the structure 
including LL) 

10 through 14 DO 46 05 63 06 

15 through 18 DATBLK, a 4-byte field, the data block number 

being sent 
C0 80 

21,22 LD, a 2-byte length field (6 + length of the data) 

23 through n DATA, the data being sent . 
Bytes 0 through 7 are the buffer header. Bytes 2 and 3 are the length of the 
structured field message that begins in byte 8. The successful transmission 
response must be coded as shown above. 


When the Workstation Program receives the response from the 3270 PC 
application program, it sends it to the host in the following format: 


Byte (Decimal) | Contents (Hex) 


0,1 LL, a 2-byte length field (the length of the 
structure including LL) 


2 through 6 DO 46 05 63 06 


11, 12 CO 80 
13, 14 LD, a 2-byte length field (5 + length of the data) 
DATA the data being sent 


7 through 10 DATBLK, a 4-byte field, the data block number 
being sent 
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X‘DO’ Structured Fields, PC to Host 


Format of the Unsuccessful Transmission Response for Set Cursor 
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To indicate an unsuccessful transmission of the Set Cursor X‘D0O’ structured 
field request, the 3270 PC application program uses the WRITE-SF service 
to send a message to the host in the following format: 


Byte (Decimal) | Contents (Hex) 
0 through 7 00 00 09 00 00 00 00 00 
8 through 16 00 09 DO 45 08 69 04 xx 00 


Bytes 0 through 7 are the buffer header. Bytes 2 and 8 are the length of the 
structured field message that begins in byte 8. The unsuccessful 
transmission response must be coded as shown above. 


xx is one of the following: 


02 Arrival sequence not allowed 
5D Unsupported type 

60 Command syntax error 

62 Parameter is missing 

63 Parameter not supported 

65 Parameter value not supported 
6E Data element missing 

70 Record length = 0 

71 Invalid flag value 


When the Workstation Program receives the response from the 3270 PC 
application program, it sends it to the host in the following format: 


Byte (Decimal) | Contents (Hex) 
0 through 8 00 09 DO 45 08 69 04 xx 00 


xx is one of the values listed above. 


X‘DO’ Structured Fields, PC to Host 


Format of the Unsuccessful Transmission Response for Get 


To indicate an unsuccessful transmission of the Get X‘DO’ structured field 
request, the 3270 PC application program uses the WRITE-SF service to 
send a message to the host in the following format: 


Byte (Decimal) | Contents (Hex) 
0 through 7 00 00 09 00 00 00 00 00 
8 through 16 00 09 DO 46 08 69 04 xx 00 


Bytes 0 through 7 are the buffer header. Bytes 2 and 3 are the length of the 
structured field message that begins in byte 8. The unsuccessful 
transmission response must be coded as shown above. 


xx is one of the following: 


02 Arrival sequence not allowed 
22 Get past end of file 

3E Operation not authorized 

5D Unsupported type 

60 Command syntax error 

62 Parameter is missing 

63 Parameter not supported 

65 Parameter value not supported 
71 Invalid flag value 


When the Workstation Program receives the response from the 3270 PC 
application program, it sends it to the host in the following format: 


Byte (Decimal) | Contents (Hex) 
0 through 8 00 09 DO 46 08 69 04 xx 00 


xx is one of the values listed above. 
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X‘DO’ Structured Fields, PC to Host 


The Close X‘D0’ Structured Field 


The Close X‘D0O’ structured field request performs the logical termination of 
a connection between a file on the host system and a previously opened file 
on the personal computer system. 


Format of the Host Close Request 


The buffer sent by the host to the 3270 PC application program for the 
Close X‘D0’ structured field request must be formatted as follows: 


Byte (Decimal) | Contents (Hex) 
0 through 4 00 05 DO 41 12 


Note: The host Close request must be coded as shown above. 


When the Workstation Program receives the request from the host, it puts 
it into the buffer defined by the DEF-BUF service. The 3270 PC application 
program uses the READ-SF and GET-COMP services to receive the data in 
the following format: 


Byte (Decimal) | Contents (Hex) 
0 through 7 00 00 05 00 00 00 CO 00 
8 through 12 00 05 DO 41 12 


Bytes 0 through 7 are the buffer header. 


Format of the Successful Transmission Response 
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To indicate a successful transmission of the Close X‘DO’ structured field 
request, the 3270 PC application program uses the WRITE-SF service to 
send a message to the host in the following format: 


Byte (Decimal) | Contents (Hex) 
0 through 7 00 00 05 00 00 00 00 00 
8 through 12 00 05 DO 41 09 


Bytes 0 through 7 are the buffer header. Bytes 2 and 3 are the length of the 
structured field message that begins in byte 8. The successful transmission 
response must be coded as shown above. 


X‘DO’ Structured Fields, PC to Host 


When the Workstation Program receives the response from the 3270 PC 
application program, it sends it to the host in the following format: 


Byte (Decimal) | Contents (Hex) 
00-05 DO 41 08 


Format of the Unsuccessful Transmission Response 


To indicate an unsuccessful transmission of the Close X‘DO’ structured field 
request, the 3270 PC application program uses the WRITE-SF service to 
send a message to the host in the following format: 


Byte (Decimal) | Contents (Hex) 
0 through 7 00 00 09 00 00 00 00 00 
8 through 16 00 09 DO 41 08 69 04 xx 00 


Bytes 0 through 7 are the buffer header. Bytes 2 and 3 are the length of the 
structured field message that begins in byte 8. The unsuccessful 
transmission response must be coded as shown above. 


xx is one of the following: 
03 Close of an unopened file 
5D Unsupported type 


60 Command syntax error 
71 Invalid format 


When the Workstation Program receives the response from the 3270 PC 
application program, it sends it to the host in the following format: 


Byte (Decimal) | Contents (Hex) 
0 through 8 00 09 DO 41 08 69 04 xx 00 


xx 1s one of the values listed above. 
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X‘DO’ Structured Fields, PC to Host 


X‘DO’ Structured Fields, PC to Host 
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Save and Restore Command Procedures 


Introduction 


Any of the Save and Restore commands, Send and Receive commands, IBM 
PC DOS commands, or user-written commands (see the IBM Personal 
Computer Disk Operating System manual) can be stored as records in 
special DOS files called batch files, whose file extension is .BAT. Each 
record in the file is a command, and the sequence of such commands is 
called a command procedure. Records stored in such a filename.BAT 
file may include any of the commands mentioned above. 


The commands stored in a filename.BAT file can be invoked by typing 


filename 
in the personal computer window. 


This appendix shows you how to create various kinds of command 
procedures for the Save, Restore, Send, and Receive commands. 


Command Procedures for Save and Restore 


Suppose you want to set up your IBM 3270 Personal Computer periodically 
for a particular application and need to: 


e Restore a set of screen profiles from APPL1.SCR 

e Restore a set of autokey recordings from APPL1.REC 

e Restore a set of notepads from APPL1.NOT. 

Instead of entering three individual Restore commands and having to 
remember three user file names, you can set up a command procedure, such 
as CONFIG1.BAT, that contains the three commands. Then you need only 


enter a single word to cause the three commands to be executed. This is 
illustrated below: 


A> 
CONFIG 1 ———————— CONFIG1.BAT FILE 


INDRSTR SCREEN APPL1.SCR 


INDRSTR RECORD APPL1 .REC 


INDRSTR NOTEPAD APPL1.NOT 


Creating an AUTOEXEC.BAT File 


Creating an AUTOEXEC.Bat File 


Besides using command procedures to prepare the 3270 Personal Computer 
quickly for a particular application, most users will have a special 
command procedure named AUTOEXEC.BAT. This file initially contains 
a statement that the system supplies at the conclusion of the customization 
task. Do not alter or remove this name. You may include other desired 
commands as long as they follow the statement that the system supplies. 


If you build such a file, it is invoked automatically any time DOS is 
initialized, causing the commands in AUTOEXEC.BAT to be executed. By 
putting the appropriate Restore commands into the AUTOEXEC.BAT file 
with other desired commands, you can set up the 3270 Personal Computer 
with standard screen profiles, autokey recordings, and notepads whenever 
DOS is initialized. 


DOS initialization occurs automatically whenever the customized system 
diskette is loaded and initialized. Also, when the personal computer 
window is active and in application mode, you can reinitialize DOS at any 
time by pressing the following key sequence: 


Ctrl + Alt + Del (press these keys at the same time) 


AUTOEXEC.BAT or other command procedure files can be created by using 
the EDLIN editor supplied with DOS (see the IBM Personal Computer Disk 
Operating System manual) or any of the other file editors available for the 
IBM Personal Computer. 
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Programmed Command Procedures 


Programmed Command Procedures 
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A special programmed command precedure can be created to quickly recall 
a series of notepads previously saved. This technique requires that the user 
write a DOS command program (in BASIC or another language) to interface 
with the operator. The program can prompt the operator to press certain 
keys to page forward or backward through notepad screens, or ask for the 
“name” of a particular notepad screen to be restored. The operator 
program, after receiving input about which notepad to restore next, 
converts this input into an INDRSTR (Restore) command record with the 
correct notepad file name. The operator program then writes this new 
INDRSTR record to the disk to overlay an existing INDRSTR command 
record contained in the command procedure file. This file also contains a 
command that invokes the operator program itself. If a Loop command is 
put into this file as well, a programmed command procedure, controlled by 
operator input, is created. This is illustrated below: 


A> 
NOTE ——»> NOTE.BAT SELECT.COM 


SELECT CALL RETURN 


INDRSTR (FILENAME) 


1. REQUEST INPUT 


DISK WRITE 


2. REWRITE INDRSTR 


3. RETURN 


LOOP 


When NOTE.BAT is invoked, it first calls the SELECT.COM operator 
program. The operator program requests input that indicates which 
notepad record is to be restored next. This input is converted into an 
INDRSTR command record with the correct notepad file name. This record 
is written into the NOTE.BAT file to overlay the existing INDRSTR record. 
The SELECT.COM program then returns, causing the next command, 
INDRSTR, which was just created, to be executed. When this command has 
finished restoring the notepad, the next command, LOOP, is executed, 
causing the SELECT command to be invoked again. This starts the cycle 
over again, with new operator input into the SELECT.COM operator 
program. 


Programmed Command Procedures 


A related series of notepads can be created and their file names stored in a 
control file along with a “current notepad” pointer. This control file can be 
accessed by the operator program to step through the related notepads, 
using the pointer. Single keys can then be used to cause the operator 
program to step forward or backward through the related notepad file 
names to quickly restore them. The notepads can be used for operator 
viewing or, for example, as a source for copying saved data into 3270 edit 
screens for document creation. The following illustrates the control file 
concept: 


NOTE.BAT SELECT.COM CONTROL.FIL 
CALL 
RETURN 


SELECT CURRENT 


POINTER 


. ‘ADVANCE’ KEY 


INDRSTR (FILENAME) 2. READ CURRENT 
POINTER 


. INCREMENT 


LOOP NOTEA.001 


. WRITE CURRENT NOTEA.002 
POINTER 


. READ NOTEA.003 


NOTEA.003 


. REWRITE INDRSTR 


NOTEB.002 


. RETURN NOTEB.003 
NOTEB.004 


NOTEB.005 


The SELECT.COM program reads an operator keystroke indicating 
advance to the next related notepad. The current pointer in the control file 
is read and updated. The file name of the notepad being pointed to, 
NOTEA.003, is read in from the control file and used to build a new 
INDRSTR command record. This record is written into the NOTE.BAT file. 
SELECT.COM returns, and NOTEA.003 is restored by the INDRSTR 
command for operator viewing or other uses. 


Many variations of the illustrated programmed command procedure can be 
developed to allow program control, not only of notepad Save and Restore, 
but also of screen profiles or autokey Save and Restore. In addition, similar 
techniques can be used to control file transfer commands (see the next 
section), IBM Personal Computer DOS commands, or other user-written 
commands. 
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File Transfer Command Procedures 


File Transfer Command Procedures 
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The file transfer commands can be enter irectly from the keyboard or 
invoked indirectly by use of standard or programmed command procedures. 
Such command procedures can relieve the operator of remembering the 
complex parameters required when directly entering Send or Receive 


commands. 


te?) 


For example, you could write a general programmed command procedure. 
An operator interface program could prompt for simplified filenames and 
convert them into the required parameters for multiple Send or Receive 
operations. This is illustrated below: 


A> 
FILE —» FILE.BAT FILEFIND.COM 


FILEFIND 


CALL RETURN 


1. OPERATOR INPUTS 


SIMPLIFIED FILE 
2. REWRITE SEND OR 
RECEIVE COMMAND 
3. RETURN 


Refer to “Programmed Command Procedures” in this appendix for a more 
detailed discussion of this technique. 


Another option is to set up fixed command procedures that transfer multiple 
files to and from the host by typing in a single command, as shown below: 


A> 
FILESET 1 ————> FILESET1.BAT FILE 


Note: To use the file transfer functions, the IBM host-supported file transfer 
program, Program No. 5664-281 for VM/CMS or 5665-311 for TSO, 
must be installed at your host site. You can verify that you have the 
host file transfer program by checking the host for the presence of the 
file named IND$FILE MODULE. 


File Transfer Command Procedures 
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3270 Limitations 


Introduction 


e 3270 limitations 
e 3270 data stream functions 


e Personal computer application mode operation. 


3270 Limitations 


The following 3270 capabilities are limited or are not available with the 
IBM 3270 Personal Computer: 


e The magnetic slot reader, magnetic hand scanner, and selector light pen 
are not available as attachments. 


e The functions of port 0 of the 3270 control unit attachment that are 
available in control unit terminal (CUT) mode are Load Print Matrix 
and Test key. Port 0 of the control unit attachment is not available in 
distributed function terminal (DFT) mode. 

e The binary synchronous host copy command is not available. 

e The security keylock is not available. 

e Explicit partition is not supported on the DFT session. 

e The control unit Entry Assist feature is supported in CUT mode only. 

e X.25 and X.21 keystroke support is available in CUT mode only. 


e The APL character set is not available. 


e Encryption/decryption is available for control unit terminals (CUT 
mode) only. 


e The 3270 graphic escape is not supported. 


e The diagnostic reset dump to the control unit is supported as a reset 
only; no dump is generated. 


e The response time monitor is supported on the DFT session. 
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3270 Data Stream Functions - Interface Codes 


3270 Data Stream Functions 


This section describes the 3270 data stream functions supported by the IBM 
3270 Personal Computer. For general information on all the 3270 data 
stream functions, refer to the IBM 3270 Information Display System: Data 
Stream Programmer’s Reference. 


In this section, those functions of the 3270 data stream that are supported 
by the 3270 Personal Computer are listed, and any information unique to 
3270 Personal Computer is provided. For those familiar with the 3270 data 
stream, this information should be sufficient for most purposes. 


Interface Codes 


Data commands and orders transmitted between the 3270 Personal 
Computer and the host system are in the form of extended binary-coded 
decimal interchange code (EBCDIC) interface codes. Figure D-1 shows the 
interface codes. Figure D-2 lists the EBCDIC control character I/O codes. 
Refer to IBM 3270 Information Display System: Character Set Reference, for 


further details. 
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Figure D-1 (Part 1 of 2). United States EBCDIC I/O Interface Code 
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Notes: 


1. 


Codes X‘00’ through X‘1F’ and X‘FF’ are control codes, and codes X‘40’ through X‘FE’ are 
character codes. All blank squares in this chart represent undefined codes. All defined character 
codes are enclosed by heavy lines. Undefined control codes are rejected with a negative response 
(SNA) or an OP CHECK (non-SNA). If the extended attribute buffer (EAB) is enabled, all 
undefined character codes are accepted, stored, and returned without change on a subsequent read 
operation. If the EAB is disabled, character codes X‘CE’, X‘CF’, X‘DD’, X‘DE’, X‘EE’, X‘EF’, and 
X‘FE’ are stored, displayed, and returned as the character (X‘60’), and all other undefined 
character codes are accepted, stored, and returned without change. IBM reserves the right to change 
at any time the character displayed or printed and the I/O interface code returned for an undefined 
character code. 


CR, NL, EM, and FF control characters are displayed and printed as spaces. If extended attributes 
are not enabled, the DUP and FM control characters are respectively displayed as * and ; in 
dual-case mode. If extended attributes are enabled, DUP and FM are always displayed as * and ; 
respectively. DUP and FM are always printed as * and ; respectively. 


Bits 0 and 1 are assigned for the following characters: AID, attribute, write control (WCC), device 
address, buffer address, sense, and status. Bits 0 and 1 are assigned so that each character can be 
represented by a graphic character within the solid outlined areas of the chart. See Figure D-2. 


Figure D-1 (Part 2 of 2). United States EBCDIC I/O Interface Code 
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EBCDIC EBCDIC 
Bits 2-7 | Graphic a Bits 2-7 | Graphic a 


00 0000 10 0000 
00 0001 10 0001 
00 0010 10 0010 
00 0011 10 0011 
00 0100 10 0100 
00 0101 10 0101 
00 0110 10 0110 
00 0111 10 0111 
00 1000 10 1000 
00 1001 10 1001 
00 1010 10 1010 
00 1011 10 1011 
00 1100 10 1100 
00 1101 10 1101 
00 1110 10 1110 
00 1111 10 1111 
01 0000 11 0000 
01 0001 11 0001 
01 0010 11 0010 
01 0011 11 0011 
01 0100 11 0100 
01 0101 11 0101 
01 0110 11 0110 
01 0111 11 0111 
01 1000 11 1000 
01 1001 11 1001 
01 1010 11 1010 
01 1011 11 1011 
01 1100 11 1100 
01 1101 11 1101 
01 1110 11 1110 
011111 111111 


| UTOTACAW>B 
NK XM S<CHa: 


7: 


JOT AP POUVOZZO RAS 4+T A 
2 | Per WCONHDIPWNRrON, 


Notes: 


1. The characters in Figure D-2 are used as attribute, write control 
character (WCC), attention identifier (AID), CU and device address, and 
buffer address. 


2. To use this table to determine the hexadecimal code transmitted for an 
address or control character, first determine the values of bits 2— 7. 
Select this bit configuration from the Bits 2—7 column. The hexadecimal 
code that will be transmitted is to the right of the bit configuration. 


3. Use this table also to determine equivalent EBCDIC hex codes and their 
associated graphic characters. Graphic characters for the United States 
I/O interface codes are shown. Graphic characters might differ for 
particular World Trade I/O interface codes. For possible graphic 
differences when these codes are used, refer to IBM 3270 Information 
Display System: Character Set Reference. 


Figure D-2. EBCDIC Control Character I/O Codes 
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Attributes 


The IBM 3270 Personal Computer display stations support field attributes, 
extended field attributes, and character attributes. 


Field Attributes 


Figure D-3 shows the bit positions in the field attribute byte. Figure D-4 
shows the bit assignments for the field attributes supported by the IBM 3270 
Personal Computer. 


xr [ur [AN [D/sPp [0 [MDT 
ff fe fs [es le |r 


Figure D-3. Field Attribute Byte Bit Positions 


EBCDIC 
Bit Field Characteristics 


Value determined by contents of bits 2—7. 
See Figure D-2 for hexadecimal values. 


Always 1 


Unprotected 
Protected (see Note) 


Alphanumeric 

Numeric (if numeric lock capability is activated, 
causes automatic numeric shift of keyboard) (see 
Note) 


00 
01 
10 
11 


Display not detectable by CrSel key 
Display detectable by CrSel key 
Intensified display detectable by CrSel key 
Nondisplay, nonprint, nondetectable 


to i ll 


Reserved — Always 0 


Modified data tag (MDT); identifies modified fields during 
Read Modified command operation: 


0 Field has not been modified 
1 Field has been modified by the operator. Can also 
be set by program in data stream. 


Note: Bits 2 and 3 equal to 11 causes an automatic skip. 


Figure D-4. Field Attribute Character Bit Assignments 
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Extended Field Attributes and Character Attributes 


The IBM 3270 Personal Computer supports the attribute types and attribute 
values in Figures D-6 through D-8 as extended field attributes (EFAs) and 
as character attributes (CAs). All other attribute types and attribute values 
are rejected with a negative response (SNA) or an OP CHECK (non-SNA). 


The attribute structure used for extended field attributes defines all 
characteristics with attribute type-value pairs, as shown in Figure D-5. 
Each attribute type has associated with it a set of attribute values. 


Attribute type Attribute value 


Figure D-5. The Structure of an Attribute Pair 


Attribute | Attribute 

ee (Hex) | Value (Hex) 
Sc Default (to EFA) 
Blink Blink 


Reverse Video Reverse Video 
Underscore Underscore 


Figure D-6. Attribute Type X‘41’ — Extended Highlighting 


Attribute Attribute 
<vee (Hex) | Value (Hex) 


Default aT (to EFA) 
Blue Blue 
Red Red 


Pink Pink 
Green Green 
Turquoise Turquoise 
Yellow Yellow 
White White 


Figure D-7. Attribute Type X‘42’ — Color 


Attribute Attribute LCID 
ae (Hex) | Value (Hex) | EFA Default 
Default | Default (to EFA) 


Reserved 
PSA PSA 


PSB PSB 
PSC PSC 
PSD PSD 
PSE PSE 
PSF PSF 


Figure D-8. Attribute Type X‘43’ — Character Set Selection 
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Commands 


For a description of the functions of the following commands, see the IBM 
8270 Information Display System: 8274 Control Unit Description and 
Programmer’s Guide, GA23-0061. 


3270 Data Stream Commands 


The control unit internally translates the non-SNA channel command codes 
into the SNA/BSC form before transmitting this information to the 3270 
Personal Computer. Figure D-9 shows these commands. 


Non-SNA 
Command ee Channel Graphic 
a 1 


Write 
Erase/Write 
Erase/Write 
Alternate 
Write 
Structured 
Field 
Erase All 
Unprotected 
Read Buffer 
Read Modified 
Read Modified 
All 


Figure D-9. 3270 Data Stream Commands 


Non-SNA Channel Commands 


Although not part of the 3270 data stream, the channel commands in 
Figure D-10 are valid for non-SNA channel-attached 3270 Personal 
Computer display stations. 


The 3270 Control Unit internally decodes the following commands and 
parses the appropriate Write, Read Modified, or Read Buffer SNA/BSC 
command code values to the IBM 3270 Personal Computer. 


Non-SNA Channel 
Command Code 
Command Mnemonic EBCDIC (Hex) 


No Operation 

Sense 

Select Read Modified 

Select Read Buffer 

Select Read Modified from 
Position 

Select Read Buffer from Position 

Select Write 


Select RM 
Select RB 
Select RMP 


Select RBP 
Select WRT 


Figure D-10. Non-SNA Channel Commands 


Write Control Character 


Write Control Character 


The write control character (WCC) bits have the following significance for 
the 3270 Personal Computer: 


WCC 
Bit 


0 


1 


2,3 


Explanation 
No function. 


No function for the WRT command. Reset function, if set to 1, for 
EW and EWA commands. See Figure D-11 for the effects of the reset 
function when the 3270 Personal Computer is in implicit partition 
state. 


Reserved. 


Start printer (SNA only). When set to 1, initiates a local-copy 
operation at the completion of the write operation. If no printer is 
available, a negative response X‘0801’, X‘082KH’, or X‘082F”’ is 
returned. 


Sound alarm. When set to 1, causes the audible alarm to sound. 


Keyboard restore. When set to 1, causes keyboard operation to be 
restored (by resetting the system lock or WAIT indicator) and resets 
the AID byte to X‘60’. 


Reset MDT bits in field attributes (WRT command only). When set 
to 1, causes MDT bits to be reset to 0 in all field attribute bytes in 
the specified partition, before any orders or data characters are 
processed. 


Appendix D. Technical Notes D-9 


Write Control Character 
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Reset Condition Implicit Partition State 


1. WCC following Erase/Write 
or an Erase/Write Alternate 
command. 


a. WCC = Reset. Execute the command; reset the 


inbound reply mode to field. 


b. WCC = No Reset. 


WCC following a Write 
command. 


Execute the command. 


a. WCC = Reset or no reset. Execute the command. 


WCC in outbound 3270DS 
header, and the function is 
Erase/Write or Erase/Wriie 


Alternate 


a. WCC 


= Reset. If the PID equals 0, execute the 
function (except for screen-size 
changes) and reset the inbound 
reply mode to field. If the PID 
does not equal 0, reject with a 


negative response 


If the PID equals 0, execute the 
function. If the PID does not 
equal 0, reject with a negative 
response. 


No reset. 


WCC in outbound 3270DS 
header, and the function is 
Write. 


Execute the function if the PID 
equals 0; otherwise, reject with a 
negative response. 


a. WCC = Reset or no reset. 


Figure D-11. Write Control Character Reset Actions 
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3270 Data Stream Orders 


The IBM 3270 Personal Computer supports the 3270 data stream orders 
shown in Figure D-12. 


Order Code 
Order EBCDIC (Hex) 

Start Field SF 1D 

Start Field Extended! SFE 

Set Buffer Address SBA 

Set Attribute! SA 

Modify Field! MF 

Insert Cursor IC 


Program Tab PT 


Repeat to Address RA 


Erase Unprotected to Address 


1 The SFE, SA, and MF orders are valid only when the extended attribute buffer (EAB) is 
enabled for the logical terminal to which the order is directed. When the EAB is not enabled, 
these orders are rejected with a negative response (SNA) or an OP CHECK (non-SNA). 


Figure D-12. 3270 Data Stream Orders 
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Outbound 3270 Data Stream Structured Fields 


D-12 


The Write Structured Field (WSF) command (X‘F3’) is used by the host 


_ program to transmit the following outbound structured fields to the 


addressed logical terminal. 


Outbound Structured Field ID Code Type 
Set Reply Mode X‘09’ 
Erase/Reset X‘03’ 
Outbound 3270DS X‘40’ 
Write X‘FV 
Erase/Write X‘F5’ 
Erase/Write Alternate X‘7E’ 
Erase All Unprotected X‘6F’ 
Read Partition XO 
Read Buffer — XSFQ’ 
Read Modified X‘FO’ 
Read Modified All (SNA only) X‘6E’ 
Query X‘02’ 
Query List X‘03’ 
Load Programmed Symbols X‘06’ 
Destination/Origin X‘OF’ X‘02’ 


All other structured-field ID codes are rejected with a negative response 
(SNA) or an OP CHECK (non-SNA). 


Outbound 3270 Data Stream Structured Fields 


Set Reply Mode Structured Field Format 


The set reply mode structured field specifies the reply mode required in all 
subsequent inbound data streams. The specified reply mode remains in 
effect until it is changed by one of the following: 


Another set reply mode structured field, specifying a different reply 
mode 


An erase/reset structured field 


An EW or EWA command or a structured field with the WCC bit 1 set 
to 1, causing a reset function. 


Figure D-13 shows the contents and meanings for bytes 0 through 5 and 7. 


Highlighting selection (Notes 1 and 3) 


X‘0005’ 
through 


Partition identifier (must be X‘00’ for 
implicit partition state) X‘00’ — X‘OF’ 


Reply mode requested 
Field mode (default) 
Extended field mode 
Character mode 


Color selection (Notes 1, 2, and 3) 


Notes: 


More than five bytes can be present only when character mode (X‘02’) is 
requested. Only when the length code is greater than X‘0005’ can the 
operator select from the keyboard the attribute value to be associated with 
the keyed data as shown in byte 5 above. 


If color selection (X‘42’) is specified, the structured field is accepted, but 
the operator is not allowed to select color attributes from the keyboard. 


X‘41’ and X‘42’ can appear in any order, not necessarily as shown in 
bytes 5 and 7 above. 


Figure D-13. Set Reply Mode Structured Field Format 
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Outbound 3270 Data Stream Structured Fields 


Erase/Reset Structured Field Format 


The erase/reset structured field creates an implicit partition 0 of default or 
alternate size, as specified in the structured field. Inbound-reply mode is 
reset. Figure D-14 shows the contents and meanings for bytes 0 through 3. 


X‘0004’ Length of structured field in bytes 
X‘03’ Erase/Reset ID code 
3 


a Size of usable area: 


Default size 
Figure D-14. Erase/Reset Structured Field Format 


Alternate size 


If byte 3 contains any value other than X‘00’ or X‘80’, the structured field is 
rejected with a negative response (SNA) or an OP CHECK (non-SNA). 


Outbound 3270DS Structured Field Format 
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The outbound 3270DS structured field is used to direct the write commands 
to a specified partition. The write commands are: 

e Write 

e Erase/Write 

e Erase/Write Alternate 

e Erase All Unprotected. 


Figure D-15 lists the contents and meanings for this structured field. 


Length of structured field in bytes 


X‘40’ Outbound 3270DS ID code 


Write-type command code 
Write 

Erase/Write 
Erase/Write Alternate 
Erase All Unprotected 


Figure D-15. Outbound 3270DS Structured Field Format 


The remaining bytes of the structured field are the same as for the specified 
Write command. 


WCC bit 1 set to 1 does not reset the IBM 3270 Personal Computer to 
implicit partition state, as it does for the nonstructured-field command, but 
resets the reply mode of the inbound partition to field mode. WCC bit 4 set 
to 1 specifies Start Print and must be in the last structured field of the 
string of structured fields. 


Outbound 3270 Data Stream Structured Fields 


Read Partition Structured Field Format 


Figure D-16 describes the contents and meanings for the read partition 


structured field. 


Content 


REQTYP 


B‘00’ 
BOV 
B‘10’ 
BY 


Partition identifier 
X‘00’ through X‘OF’: read operations 
X‘FF’ (physical terminal): query operations 


The type of operation to be performed: 


Read Modified (RM) 

Read Modified All (RMA) 

Read Buffer (RB) 

Query 

Query List 

Request Type — present only for 
Type = X‘03’ (Query List): 


Only list (bytes 6 through n) 
Query Equivalent + list 
All Query Replies 

Reserved 


Reserved 


Figure D-16. Read Partition Structured Field Format 


For Query (Type = X‘02’), the structured field ends after byte 4. 


For Query List (Type = X‘03’), byte 5 is a flag byte called REQTYP, 
described below. Bytes 6 through n contain the type codes of the Query 
Reply (or Replies) being requested. 


e REQTYP — Request Type (present only if TYPE = X‘03’): 


— B‘00’ indicates the only Query Replies being requested are those 
specified in bytes 6 through n. If the value is B‘00’ but no list is 
present (count field is valid), a Null Query Reply is returned. 


— B‘O1’ indicates all the Query Replies that would be sent in reply toa 
Query are sent, in addition to those (if any) that are specified in the 
list (bytes 6 through n). No duplicate Query Replies are sent. For 
example, if the list requests a Query Reply that would be sent 
anyway, because of the B‘01’ flag, the Query Reply is sent only 


once. 
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Inbound 3270 Data Stream 


~— B‘10’ indicates that all the query replies that are supported are sent. 
If a list is present (bytes 6 through n), B‘10’ overrides the list (that 
is, the list is ignored). 


The same type code may appear more than once in the list (bytes 6 
through n). However, only one Query Reply will be returned for a 
particular type code value, regardless of how many times it appears 
in the list. 
All type code values are valid in the list. Those type codes not 
supported are ignored. However, if none of the type codes in the list 
are supported, a null Query Reply is returned. 


Restrictions: 


1. The Read Partition structured field must be the last structured field 
in the current outbound transmission. 


2. The IBM 3270 Personal Computer must be in normal-read state, and 
the PID must specify a valid partition. 


Any of the following conditions causes an error and the return of an 
appropriate sense code in SNA sessions or OP-CHECK in non-SNA 


sessions: 


— The IBM 3270 Personal Computer display is in normal-read state, 
and the identified partition does not exist: sense code X‘1005’. 


— The command code is invalid: sense code X‘1003’. 
— The PID value is invalid: sense code X‘1005’. 


— The read-partition structured field is not the last structured field to 
be sent in the current outbound transmission: sense code X‘1008’. 


— The IBM 3270 Personal Computer is in retry state: sense code 
X‘0871’. 


— The transmission is sent with end bracket: sense code X‘0829’. 


— The transmission does not specify “Change Direction”: sense code 
X‘0829’. 


Inbound 3270 Data Stream 
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All inbound 3270 data streams are preceded by an attention identifier (AID) 
byte that identifies the cause of the inbound transmissions. Figure D-17 
lists the possible causes of an inbound 3270 data stream, the associated AID 
values, and the resulting operations when the IBM 3270 Personal Computer 
is in normal-read state or in retry state. 


Inbound 3270 Data Stream 


Operation (Normal- Operation 
Cause AID Read State) (Retry State) 


Clear key Short read (implicit 
partition 0) 


Short read 
PA2 key Short read 
PA3 key Short read 


PF1 — PF9 keys X‘F1’-X‘F9’ | Read modified (addresses 
cm7arwency | and data of all modified 

PF10 — PF12 keys XTA-XTC fields —nulls suppressed) 

PF13 — PF21 keys X‘C1’-X‘C9’ 

PF22 — PF24 keys X‘4A’-X‘4C’ 

Cursor-select field with & | X‘7D’ 

designator or Enter key 


PA1 key 


Cursor-select field with X‘7E’ Read modified (addresses 
null or space designator of modified fields) 
Read Modified command X‘60’ Read modified Retry last AID action 
from inbound partition 
Read Modified All X‘60’ Read modified all Retry read modified all 
command from inbound partition 
Read Buffer command X‘60’ Read buffer Retry read buffer from 
inbound partition 
Read Partition- Modified Read modified 
SF 


Read Partition-Read X61’ Read modified all Negative response (SNA) 
Modified ALL SF or OP CHECK 
(non-SNA) 
Read Partition-Read X‘6L’ Read buffer 
Buffer SF 
Read Partition Query 6F [Kes [Quenyrepliee dP 


Figure D-17. Inbound 3270 Data Stream 


Inbound 3270 Data Stream for Partition 0 
Each inbound 3270 data stream for partition 0 is preceded by an AID code 
that identifies the cause of this inbound data stream. Figure D-17 lists 
each cause, the AID associated with that cause, and the resulting type of 
inbound operation. The types of inbound operations are: 
e Short read 
e Read modified 
e Read modified all 


e Read buffer. 
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Inbound 3270 Data Stream 


D-18 


Short Read Format: Figure D-18 shows that the short-read operation 
results in an inbound data stream consisting of only the AID byte. 


Attention identifier byte: 
Clear key 


PAI key 
PA2 key 
PA3 key 


Figure D-18. Short Read Format 


Read Modified and Read Modified All Format: The read-modified 
operation and the read-modified-all (SNA only) operation can take place in 
a field, an extended field, or a character reply mode. Figure D-19 shows a 
general format for all three reply modes. 


Notes: 


1. In character reply mode, the string of data characters can also include Set 
Attribute orders to indicate changes in the character attribute value. 


2. For the read-modified operation, with an AID of X‘7E’ (indicating cursor 
selection of a space or null designator character), only the addresses of 
modified fields are transmitted. . 


3. If none of the fields has been modified, the inbound data stream consists 
of bytes 0 through 2 only. 


4. If the partition buffer is unformatted, the data stream consists of bytes 0 
through 2 and bytes 6 through n (all data in the partition buffer, with 
nulls suppressed). 


Figure D-19. Read Modified and Read Modified All Format 


The pattern of bytes 3 through n is repeated for all other modified 
(MDT bit set to 1) fields. 


Inbound 3270 Data Stream 


Read Buffer Format: The read-buffer operation can take place in field, 
extended field, or character reply mode. The read-buffer operation 
transmits the contents of all buffer locations in the presentation space, 
starting at the current cursor position. 


Read Buffer Format in Field Reply Mode: Figure D-20 shows the read 
buffer format in field reply mode. 


10 ~=——s—isi*«dS AT. Attention identifier byte 


CCP Hexadecimal address of the cursor (current 
cursor position) 
Data 


3 through Data characters (including null characters, 
n but excluding Set Attribute orders), from the 
current cursor position to the start of the 


next field (see Note) 


Start Field order code 
Field-attribute character 


Data All data characters to the start of the next 
field 


Note: Set Attribute orders are defined in the IBM 3270 Information Display 
System 3274 Control Unit Description and Programmer’s Guide. 


Figure D-20. Read Buffer Format in Field Reply Mode 


The pattern of bytes n + 1 through m is repeated for all other fields being 
transmitted. 


Read Buffer Format in Extended Field and Character Mode: The read 
buffer format in extended field and character mode is shown in Figure D-21. 
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Ce EN eee Attention identifier byte 


1, 2 CP Hexadecimal address of the cursor (current 
cursor position) . 
3 through Data Data characters (including null characters), 
n 
of the next field. 


from the current cursor position to the start 
Start Field Extended order code. 
n+2 Attribute count (X‘00’ through X‘04’). The 


number of attribute specifications (byte 
pairs) that follow. 


C 


Byte pairs are transmitted only for those 
extended field attributes with specified 
(nondefault) values. 


Field-attribute type 
Field-attribute type 
Extended-field-attribute type 
Extended-field-attribute value: includes 
highlighting, color, and PS. (See 
“Attributes” in Appendix F, “Presentation 
Space Considerations.”) 


Data All data characters to the start of the next 
field. 


Notes: 


1. Set Attribute orders are defined in the IBM 3270 Information Display 
System: 3274 Control Unit Description and Programmer’s Guide, 
GA23-0061. 


2. When in character mode, each string of data characters can include Set 
Attribute orders to indicate changes in the character attribute value. The 
format for these Set Attribute orders is the same as for outbound Set 
Attribute orders. In extended-field mode, no Set Attribute orders are 
included. 


Figure D-21. Read Buffer Format in Extended Field and Character Mode 


The pattern of bytes n + 1 through m is repeated for all other fields being 
transmitted. 


Inbound Structured Fields 


Inbound Structured Fields 


The inbound structured field AID code (X‘88’) precedes and identifies the 
following inbound structured fields for transmission to the host program: 


Query Reply Structured Field ID Code Type 

Destination/Origin X‘OF”’ X‘02’ 

Inbound 3270DS X‘80’ 

Query reply X81’ 
Usable area X‘81’ 
Character sets _ X‘85’ 
Color X86’ 
Highlight X‘87’ 
Reply modes X‘88’ 
Implicit partition X‘A6’ 
DDM X‘95’ 
Auxiliary device x‘99’ 
Document Interchange Architecture X‘97’ 


Query Reply Structured Field 


The logical terminal to which the read partition query function was 
addressed responds with the transmission of a series of structured fields 
indicating the field and character attributes, the screen or page size 
characteristics, the symbol sets, and the reply modes available on the 
logical terminal. Since each structured field contains its own unique 
identification, the order in which the fields are transmitted is not 
important. The query reply structured fields and their associated reply 
codes are as follows: 


Query Reply Structured Field ID Code Type 

Query reply X‘81’ 
Usable area X‘81’ 
Character sets X‘85’ 
Color X‘86’ 
Highlight X‘87 
Reply modes X‘88’ 
Implicit partition X‘A6’ 
DDM X‘95’ 
Auxiliary device X‘99’ 
Document Interchange Architecture X‘97’ 
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Usable Area Query Structured Field Format: The usable area query 
reply structured field indicates to the host program the dimensions of the 
logical screen for the logical terminal. Figure D-22 describes the contents 
and meaning of the usable area query reply structured field. 


Length of structured field in bytes, if 
partitions are not supported (0 partitions 
defined) 


Variable-character cells not supported (omit 
bytes 23 through 26) per logical-terminal 
definition table 


Width of usable screen for logical screen 
8,9 |LSH | Height of usable screen for logical screen 
Units of measure (millimeters) 

11 Xr 


Horizontal pitch: the distance between points 
in the x-direction as a fraction measured in 
units 

2-byte numerator 
2-byte denominator 


through 


Vertical pitch: the distance between points in 
the y-direction as a fraction measured in units 
2-byte numerator 
2-byte denominator 


HS 09 Horizontal character cell size 
VS OF Vertical character cell size 


Figure D-22. Usable Area Query Reply Structured Field Format 


Inbound Structured Fields 


Character Sets Query Reply Structured Field Format: The character 
sets query reply structured field is transmitted to inform the host program 
what character sets are defined for the logical terminal. Figure D-23 
describes the contents and meaning of the character sets query reply 
structured field. 


Length of structured field in bytes 
(13 + lengths of descriptors) 


| dT xen | ID code of query reply | 
ae : ID code of character sets reply 


Based on logical-terminal definition 
table (EAB/PS) definition: 

Graphic escape not supported 
Reserved 

Load PS (EAB and PS) supported 
(0 = no;1 = yes) 

Load PS extension (EAB and PS) 
supported (0 = no;1 = yes) 

One size of character cell supported 
Reserved 


aaa 
6 Cf XO Default-character cell width 
7 | XR | Default-character cell depth 


Bese ft X‘6000 Supported Load PS format types; 
0000’ bit-encoded (if bit i = 1, then type 
2d] TL Length of each descriptor 


is supported). 
Figure D-23. Character Sets Query Reply Structured Field Format 


Appendix D. Technical Notes D-23 


Inbound Structured Fields 


D-24 


Character Set Descriptors: Figure D-24 describes the length of each 
descriptor. 


Bit 


1 


2 
Reserved Reserved 


ae ieee LCID Local character set ID 


Figure D-24. Character Set Descriptors 


Set ID Device-specific character set ID (RWS 
or ROS number) 


Loadable: 
Nonloadable character set 
Loadable character set 


Triple plane: 
Single-plane character set 
Triple-plane character set 


Reserved Reserved — must be zero 


CB 
B‘O’ 
BV’ 


Compare bit: 
LCID compare 
No LCID compare 


Reply Modes Query Reply Structured Field Format: The reply modes 
query reply structured field is transmitted, if EAB is defined, to inform the 
host program which reply modes are supported by the logical terminal. 
Figure D-25 lists the contents and meanings for bytes 0 through 6 of the 
structured field. 


Field reply mode supported 
Extended-field reply mode supported 
X‘02’ Character reply mode supported . 


Figure D-25. Reply Modes Query Reply Structured Field Format 


ea! 


Inbound Structured Fields 


DDM Query Reply Structured Field Format: Figure D-26 lists the 
contents and meanings for bytes 0 through 11 of the structured field. 


Length of structured field in bytes 
2X8 ID code of query reply 


ID code of DDM reply 
File not available 
fs__|xo [Reseed CSC“‘;<CS;*~*! 


2 
3 
4 
5 
inbound 
(il asl tsladaccreniasil 
outbound 
11 


Number of subsets supported 
fla | Xo DDM subset identifier 


Figure D-26. DDM Query Reply Structured Field Format 


Auxiliary Device Query Reply Structured Field Format: Figure D-27 
lists the contents and meanings of the bytes in the auxiliary device query 
reply structured field, which indicates direct access support of one or more 
auxiliary devices. 


: 
25 


ID code of auxiliary device reply 
4 Reserved | Must be X‘0000’ 
flags 
Figure D-27. Auxiliary Device Query Reply Structured Field Format 
When one or more auxiliary devices is supported (3270 data stream work 
stations), this query reply is transmitted inbound to a Query List or to a 
Query. This query reply indicates support of: 
e Destination/origin structured field 


e Query list structured field 


e One or more auxiliary devices. 
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Document Interchange Architecture Query Reply Structured Field 
Format: The contents and meanings of the bytes in the document 
interchange architecture query reply structured field are shown in 
Figure D-28. 


Length of structured field in bytes 
ID code of query reply 


X‘97’ ID code of Document Interchange Architecture 
query reply 
01’ 


Reserved | Must be X‘0000’ 

flags 

X‘0800’ Maximum DIA bytes per transmission allowed 
inbound 

X‘0800’ Maximum DIA bytes per transmission allowed 
outbound 

x* Number of 3-byte function set identifiers that 
follow 


1 —"13 X‘01000B’ | DIAL function set identifier 


Figure D-28. Document Interchange Architecture Query Reply 
Structured Field Format 


Direct Access ID Self-Defining Parameter: Figure D-29 lists the contents 
and meanings of the bytes in the direct access ID self-defining parameter. 


iO. =~. PMOL = 1 Parameter length in bytes 


Destination/origin identification 


Figure D-29. Direct Access Self-Defining Parameter 


Inbound Structured Fields 


Color Query Reply Structured Field Format: The color query reply 
structured field indicates to the host the color that will be displayed for 
each color attribute value. Figure D-30 describes the contents and 
meanings of the bytes in this structured field. 


x 


08’ Length of attribute list (number of 
color attribute pairs) 
Default color attribute 
Green is the default device color. 


X‘F1FIF2F2 For color display, each color maps to 
F3F3F4F4 itself. 
F5F5F6F6 
F7F7 


X*FLF4F2E4 
F3F4F4F4 
FOF4F6F4 

F7F4’ 


ee 


8 through 21 
8 through 21 


Notes: 


For monochrome display, each color 
maps to green. 


1. Bytes 6 and 7 are always used to indicate the IBM 3270 Personal 
Computer default color. 


2. If “extended attributes” is not enabled by the logical-terminal definition 
table, the color query reply is not returned. 


Figure D-30. Color Query Reply Structured Field Format 
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Highlight Query Reply Structured Field Format: The highlight query 
reply is transmitted inbound as a structured field with the format shown in 
Figure D-81. 


X‘000D’ Length of this structured field in bytes 


ID code of query reply 

ID code of highlight reply 

X‘04’ Number of byte pairs that follow 
5 


[s__[X00" | Acceptable attribute value SOS 
[6 [XP | Defaulthighlight action code 
fs__[XFY | Blink action code ——SSSCSCSC~CS—SCSCS 
[9 [ra | Accepted attribute value 


Notes: 


1. Bytes 5, 7, 9, and 11 of a highlight query reply indicate to a host the 
attribute values that the IBM 3270 Personal Computer: 


a. Can accept in an outbound extendea-highlight attribute byte 
b. Will preserve and will return to the host in a subsequent inbound 
operation (unless changed by the operator) 


2. Bytes 6, 8, 10, and 12 indicate to a host what action the IBM 3270 
Personal Computer performs for each of those attribute values. 


3. If “extended attributes” is not enabled by the logical-terminal definition 
table, the highlight query reply is not returned. 


Figure D-31. Highlight Query Reply Structured Field Format 


Inbound Structured Fields 


Implicit Partition Query Reply Structured Field Format: The implicit 
partition query reply structured field is always returned by the IBM 3270 
Personal Computer logical terminal. It informs the host of the default and 
alternate sizes for the target logical terminal’s implicit partition. It may 
also return the cell size in effect for the default and alternate sereen sizes. 
Figure D-32 shows this structured field format. 


[2 | X81" | WDeode of query reply 


Figure D-32. Implicit Partition Query Reply Structured Field Format 


Implicit Partition Default and Alternate Screen Size: For an SNA 
session, the default and alternate screen sizes returned in this reply are 
those established by the BIND for this logical terminal. 


For a non-SNA session, the default and alternate screen sizes returned in 
this reply are those in effect for this logical terminal at the time the reply is 
generated. 


Character Cell Dimensions: The dimensions of the character cells in 
effect for the default and alternate screen sizes are returned only when the 
character cell size for either the default or the alternate implicit partition is 
different from the cell size specified in the usable area query reply. 
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Self-Defining Parameters: The implicit partition size parameter shown in 
Figure D-33 is always returned as part of the implicit partition query reply. 


Parameter of screen size dimension 
Reserved 


Notes: 


1. Bytes 3and 4: For an SNA session, the width of the default implicit 
partition is the value established at logical-terminal bind time. For a 
non-SNA session, the width of the default implicit partition is 80. 


2. Bytes 5and 6: For an SNA session, the height of the default implicit 
partition is the value established at logical-terminal bind time. For a 
non-SNA session, the height of the default implicit partition is 24. 


3. Bytes 7 through 10: For an SNA session, the width and the height of the 
alternate implicit partition are the values established at logical-terminal 
bind time. For a non-SNA session, the width and the height of the 
alternate implicit partition are the values defined in the logical-terminal 
definition table. 


Figure D-33. Self-Defining Parameters 
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Transmission of Buffer Addresses 
The following text describes: 
1. The relationship between a given row/column position in a logical 
terminal’s presentation space and its address in the logical terminal’s 


buffer storage. 


2. How a buffer storage address is transmitted to and from the IBM 3270 
Personal Computer in each of the two address modes. 


Buffer Addresses 
The relationship between any given row/column position in a logical 
terminal and its address in the logical terminal’s buffer storage is expressed 
thus: 

Buffer address = W x (R-1) + (C-1) 
Where: 
W is the logical terminal width (number of columns). 
Ris the row number (counting from 1) of the position being addressed. 
Cis the column number (counting from 1) of the position being addressed. 
Note: For column 1, row 1, the buffer address is 0. 
Example of Buffer Address Calculation: Given a logical terminal width 
(W) of 50 columns, the buffer address of the character location in column 46 
and row 21 is: 
Buffer Address = (50 x 20) + 45 = 1045 

Transmission of a Buffer Address 
A buffer address is always transmitted in a 2-byte field. 
The way in which a buffer address is transmitted depends on the address 
mode for the logical terminal. For example, it may be transmitted in the 
two bytes after the X‘11’ byte in a Set Buffer Address order, or in the two 
bytes that specify the current cursor position in an inbound read operation. 
A logical terminal has one of two address modes: 


e 16-bit address mode 


e@ 12/14-bit address mode. 
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Transmission of a Buffer Address in 16-Bit Address Mode 


In 16-bit address mode, buffer addresses are transmitted outbound and 
inbound as 16-bit binary numbers. 


Transmission of a Buffer Address in 12/14-Bit Address Mode 
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In 12/14-bit address mode, bits 0 and 1 of the first address byte have the 
following bit significance: 


00 — 14-bit binary address follows 
01 — 12-bit coded address follows 
11 — 12-bit coded address follows 


(In an outbound transmission, if bits 0 and 1 of the first byte are set to 
B‘10’, a sense code of X‘1005’ is returned.) 


For outbound transmissions, the IBM 3270 Personal Computer uses these 
first two bits to determine whether the address in the transmission has 12 
bits or 14 bits. For inbound transmissions, the size of the logical terminal 
determines whether the address in the transmission has 12 bits or 14 bits. If 
the logical terminal size is greater than 4096 bytes (excluding character 
attributes if an EAB device), 14-bit addresses are used. Otherwise, 12-bit 
addresses are used. 


14-Bit Addresses: 14-bit buffer addresses are transmitted outbound and 
inbound with bits 0 and 1 of the first byte equal to B‘00’, followed by the 
buffer address expressed as a 14-bit binary number. 


12-Bit Addresses: 12-bit buffer addresses are transmitted outbound and 
inbound with the following format: 


Where: 


a represents the binary value of the address (12 bits), and BB is B‘01’ or 
B‘1l’ (see text below). 


The 12-bit address EBCDIC values for decimal addresses 0 through 10879 
are derived as follows: 


1. The 12-bit binary representation of the decimal address is split into two 
6-bit groups. 


2. The more significant 6-bit group occupies bits 2 through 7 of the first 
byte. 


3. The less significant 6-bit group occupies bits 2 through 7 of the second 
byte. 


Transmission of Buffer Addresses 


4. According to the value of bits 2 through 7 in each byte, bits 0 and 1 of 
each byte are set to obtain the hexadecimal representations, as defined 
in Figure D-34. The resulting EBCDIC value represents a graphic 
character in the range X’40’ through X‘F9’. 


Bits 27 | BBY | Bits 2-7 | BBY | Bits 27 | BBY | Bits 27 | BBY 


00 0000 
00 0001 
00 0010 
00 0011 
00 0100 
00 0101 
00 0110 
00 0111 
00 1000 
00 1001 
00 1010 
00 1011 
00 1100 
00 1101 
00 1110 
00 1111 


01 0000 © 
01 0001 
01 0010 
01 0011 
01 0100 
01 0101 
01 0110 
01 0111 
01 1000 
01 1001 
01 1010 
01 1011 
01 1100 
01 1101 
01 1110 
01 1111 


10 0000 
10 0001 
10 0010 
10 0011 
10 0100 
10 0101 
10 0110 
10 0111 
10 1000 
10 1001 
10 1010 
10 1011 
10 1100 
10 1101 
10 1110 
10 1111 


11 0000 
11 0001 
11 0010 
11 0011 
11 0100 
11 0101 
11 0110 
11 0111 
11 1000 
11 1001 
11 1010 
11 1011 
11 1100 
11 1101 
11 1110 
11 1111 


* EB = EBCDIC 


Note: The 12-bit address EBCDIC values for decimal addresses 0 
through 3568 are listed in the IBM 3270 Buffer Address Codes. 


Figure D-34. Hexadecimal Representations 
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Changes or Limitations to the Personal Computer 


Session 


Following are the changes or limitations to the PC session in application 
mode when operating under the workstation program Note that if you are 
running a PC application program through the IBM 3270 Workstation 
Program, there may be unpredictable results in some cases. 


Non-3270 PC Hardware Restrictions 


The following restrictions apply to non-3270 PC hardware (XT and AT). 
Failure to follow these guidelines on the use of non-3270 PC hardware could 
result in system failure. 


For Uni-DOS on non-3270 PC hardware, an application is assumed to be 
ill-behaved. The application will be suspended when: 


— It is not the top or active window 
— The WSCtrl key is pressed. 


Ill-behaved applications will run only in an active session. If an 
ill-behaved application exits and stays resident in the active session, 
then any other application you run in that session will be seen as 
ill-behaved and will never run in the background. 


On non-3270 PC hardware, ill-behaved applications will be displayed 
full-screen when they are made active even if they are sized. 


Even if you sized your windows using the API, they may be forced to 
full-screen and appear enlarged when active under the following 
conditions: 


— Your application uses graphics mode 
— Your application uses 40-column mode 
— Your application writes directly to the screen. 


Note: The Browse function will not work on applications forced to 
full-screen size. 


When using work station control API, the WS Ctrl OIA will not be 
displayed on either a Uni-DOS or Multi-DOS system under the following 
conditions: 


— Your application uses graphics mode 
— Your application uses 40-column mode 
— Your application writes directly to the screen. 
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e If you are running an ill-behaved application in a PC session, the shift 
state of that session may not remain as you originally set it after 
jumping to other windows and back again. For instance, if you have set 
Caps Lock on in this PC session, your session may be in lowercase mode 
when you jump back to it from another window. 


e Input Control API is not supported for sessions running ill-behaved 
applications that read port 60 directly. 


e Do not run PC applications that reprogram the timer. This could cause 
host communication failure. 


e Batch files will only run in the active window. To IPL your system 
completely, you must jump to the session that contains your 
AUTOEXEC.BAT file. 


e Applications that send or receive keystrokes from the host session will 
not run under Uni-DOS in a non-3270 PC XT system. 


e Applications that write directly to the display adapter registers may not 
be restored properly after jumping to another window and back again. 


Personal Computer Physical Cursor 


Auto-windowing in the PC session occurs only in response to the movement 
of the PC session physical cursor. That is, the IBM 3270 PC window always 
follows and keeps the physical cursor within its viewable area. Some IBM 
Personal Computer application programs do not use the physical cursor, 
but use other types of cursors. These other types of cursors will not 
support the auto-windowing function. If you want auto-windowing to 
occur, you must convert such applications to use the physical cursor, or 
keep the physical cursor updated and in synchronization with the logical 
cursor. 


If an application has inhibited the default cursor but you chose an alternate 
cursor, the alternate cursor will be the cursor you see. 


On non-3270 PC hardware, your cursor may have changed its position in a 
PC session after you have jumped to another session. Press the spacebar to 
return the cursor to its original position. 


Personal Computer Print Spooling 


If you are running Uni-DOS, the DOS print spooler will not operate in a PC 
session and should never be activated. If you use the print spooler, it may, 
and in most instances will, cause the control unit communication session to 
terminate. See “Control Unit Communication Session Termination” below 
for other causes of session termination. 


If you are using DOS Version 3.3 in a Multi-DOS PC session, you can use 
print spooling without any control unit communication problems. 
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Control Unit Communication Session Termination 


The PC application actions that may, and in most instances will, cause the 
control unit communication session to terminate are: 
e Use of the disable/enable functions for an extended period of time 


e Failure to issue an end-of-interrupt on a hardware interrupt level for an 
extended period of time 


e Masking of selected interrupt levels for an extended period of time 


e Failure to issue an IRET for an extended period of time. 


IBM 3270 Personal Computer Failure 


Color Limitations 
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The 3270 Personal Computer will, in most cases, fail in an unpredictable 
manner if you: 

e Use interrupt vectors X‘50’ through X‘57’ or X‘7A’. 

e Program the Intel 8259 Interrupt Controller timer chip. 

e Program channel 0 or 1 of the Intel 8253 timer chip. 

e Program the mode bits of any channel of the Intel 8253 timer chip. 


e Program group A of the Intel 8255 programmable peripheral interface 
(PPI) chip. 


e Program the Mode register of the Intel 8255 PPI chip. 
e Take over hardware interrupt 2 (3270 PC adapter). 


e Disable interrupts for an extended period of time. 


Note: This section does not apply to non-8270 PC hardware. 


The 3270 Personal Computer supports eight colors for personal computer 
applications. If you use the Personal Computer color printer to print a 
Personal Computer color graphics screen in medium resolution graphics, 
the 3270 Workstation Program uses the blue color to determine which color 
palette is displayed. In palette 0 there is no blue, and the colors printed are 
black, blue, and pink. If you change the background color to green, blue, 
turquoise, or white while using palette 0, the blue color gun is turned on 
and the colors for palette 1 are used. The color palette select register is 
Write only and cannot be checked. 


Changes or Limitations to the Personal Computer Session 


Notes on All-Points-Addressable Graphics 
Note: This section does not apply to non-8270 PC hardware. 


If you use the IBM Personal Computer all-points-addressable (APA) 
graphics applications on the IBM 3270 Personal Computer, your graphics 
images may appear differently. For example, you may have ovals in place 
of circles. For images to appear normally on the IBM 3270 Personal 
Computer, you must set the aspect ratio parameters in the application 
program. For example, in BASIC, add the aspect ratio parameter to the 
CIRCLE command to get circles instead of ovals on the display screen. 
Following is a table that shows the aspect ratios for the IBM 5153 Color 
Graphics Display, the IBM 5154 Enhanced Color Graphics Display, and the 
IBM 3270 Personal Computer Color Display. 


5153 5154 3270 Personal 
Full-Screen Personal Personal Computer Color 
Mode Computer | Computer | Display 


Medium 


5:6 35:24 B0s21 
resolution (approx 5:4) 
High resolution 5:12 35:48 35:54 
(approx 5:8) 


Note: The current aspect ratio parameters are also available dynamically. A 
video interrupt (INT X‘10’) must be made to BIOS. Register AH must 
contain X‘30’. This function call causes an address to be returned in 
CX (segment) and DX (offset), which points to the aspect values in two 
hexadecimal bytes: X‘23’ and X‘36’ for high resolution, or X‘23’ and 
X‘1B’ for medium resolution. The BIOS character generator cannot 
be used while in full-screen mode. 


Using the Full-Screen APA Mode 
Note: This section does not apply to non-3270 PC hardware. 


When emulating the IBM Personal Computer Color Graphics Adapter, note 
that approximately one-half of the display screen is used (640 x 200 PELs). 
In addition, the APA adapter is capable of displaying 720 x 350 PELs. To 
set this full-screen mode, a video interrupt (INT X‘10’) must be made to 
BIOS. For high-resolution full-screen graphics mode (720 x 350 PELs), 
register AH must contain X‘00’ and register AL must contain X‘30’ or X‘32’. 
For medium-resolution full-screen graphics mode (360 x 350 PELs), register 
AH must contain X‘00’ and register AL must contain X‘31’. Colors 
associated with these modes are shown in the table below. 
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Display Screen PEL) 


For either full-screen graphics mode, the storage addressing scheme 

changes from the standard IBM Personal Computer odd/even scans to a 

simpler, contiguous map of 32K bytes starting at ‘B8000’. For example, the 

first byte of the second scan line is addressed as 90 (X‘5A’). The IBM 

Personal Computer screens use the standard IBM Personal Computer map. 
Changing the Cursor Size or Position 

Note: This section does not apply to non-3270 PC hardware. 


PC applications control the size and position of the cursor by writing to a 
pair of I/O registers, as described in the JBM Personal Computer Technical 
Reference. 
The 6845 index registers X‘0A’ and X‘0OB’ are used for the cursor size. Index 
registers X‘0E’ and X‘0OF’ are used for the cursor position. Applications that 
do not use BIOS or DOS services for this must write these register pairs in 
the following order. For size, specify: 

‘X‘0A’ followed by X‘OB’ 


For position, specify: 


X‘OE’ followed by X‘OF” 


Personal Computer Session Screen Size 
Note: This section does not apply to non-8270 PC hardware. 


PC applications can control the screen size of the PC session. Only the 
screen size of 25 x 80 is supported by the 3270 Workstation Program. 
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This appendix describes the problem determination procedures to follow if a 
system error occurs during API activity in your application program. 


Problem Determination Procedures 


If a system error occurs during API activity, you should follow your local 
procedures for problem determination and: 


1. 


If the return code indicates that you are out of system resources such as 
RQEs or TCBs, or if the name table is full, you must do the following: 


a. Ifthe error occurred in a system extension, you must increase the 
resource requirements in the SIF for that system extension. See 
Chapter 24, “Coding System Extensions,” for information on SIFs. 


b. Ifthe error occurred in an application program, you must increase 
the requirements in the INDIBM2 SIF file. See the JBM 3270 
Workstation Program User’s Guide and Reference for information on 
updating the INDIBM2 SIF file. 


Record the return code that indicates that a system error occurred, and 
also record whether the return code was in the CL register, in the 


parameter list, or in the communication status code. 


Dump the system, using the procedures outlined under “Dump Data 
Utilities” in this appendix. 


Turn on trace events 45, 46, 47, and 48. Instructions on using the trace 
facility are given under “Using the Trace Command” in this appendix. 


Rerun the application that caused the system error. 
If the system error occurs again: 


a. Save the results of the first system dump, and dump the system 
again. 


b. Follow your local procedures, and report the problem to your 
service coordinator. 


If the system error does not occur again, follow your local procedures 
and report the system error occurrence to your service coordinator. 


Dump Data Utilities 


Dump Data Utilities 


The dump data utilities prepare formatted dump diskettes, take a dump, and 
then display: 


e Dumps of memory 
e Dumps of the trace buffer 


e Dumps of error counters. 
The three basic steps you follow to use these utilities are: 
1. Preparing formatted dump diskettes 
2. Taking the dump 
3. Displaying the dump. 
Preparing Formatted Dump Diskettes 


To use the dump facility, you must start by preparing a formatted dump 
diskette(s). To do this, perform the following steps: 


1. IPL DOS and have available the diskette that contains the INDPREP 
utility. 


2. Format and externally label the number of diskettes according to the 
chart below. 


Remember: 


a. The diskettes cannot contain any bad sectors. 
b. Do NOT use /s as a FORMAT command parameter. 


Number of Externally 
Type of Diskettes Label the 
Diskette Needed Diskette(s): 
5-1/2-inch 360 Kb 3 DUMPDATA.001 
DUMPDATA.002 
. DUMPDATA.008 


3-1/2-inch 720 Kb z DUMPDATA.001 

DUMPDATA.002 
High-Density 1 DUMPDATA.001 
1.2 Mb or greater 


With the DOS diskette in the active drive, type: 


format a: 
or: 


format b: 
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Taking the Dump 
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4. 


5. 


Note: Refer to the DOS manual to ensure that you are using the correct 
parameters for the FORMAT command (for example, /4 to format a 
360K double-sided diskette in a high-capacity drive). 

After formatting the recommended number of diskettes, insert the 

diskette containing the INDPREP utility into the active diskette drive 

and type: 

INDPREP a: 

or: 

INDPREP b: 


Press Enter. 


You will be prompted to insert the diskette(s) just formatted. 


At the conclusion of the INDPREP utility, the following message appears: 


INDDPOO3 Dump diskette(s) ready for use 


You have generated the dump diskette(s) to use only when you need to take 
a dump. 


Notes: 


1. 


If you have an XMA (expanded memory adapter) installed, it may take up 
to 6 minutes to complete the dumping process. 


If you used the IBM 3270 Workstation Program Keyboard Definition 
Utility to redefine the keyboard layout, when you are prompted to “Press 
D to take a dump...” you must press the “original” D key to take the 
dump. 


If you need to use the dump facility for problem determination procedures, 
you may take a dump in one of four ways: 


1. 


By pressing the D key in response to an INDSY001 or INDSY002 
message. 


By pressing the Alt + Ctrl + Test keys (Alt + Ctrl + Scroll Lock on 
an enhanced PC keyboard, Alt + Ctrl + {+} on an XT or AT 
keyboard). The following prompt message will appear: 


INDSYOO1 Unrecoverable System Error ~- 72060000 Press D to 
take a dump or any other key to re-IPL 


By turning TRACE off with the dump option. To do this, type TRACE 
OFF/D. The following prompt message will appear: 


Dump Data Utilities 


By pressing the Non-Maskable Interrupt (NMI) pushbutton, if present, 
on the back of the system unit. Use the NMI pushbutton if the 
keyboard does not respond. The following prompt message will appear: 


INDSYOO1 Unrecoverable System Error - 72050000 Press D to 
take a dump or any other key to re-IPL 


After pressing the D key in response to one of the above system messages: 


1. 


2. 


You will be prompted to insert diskette DUMPDATA.001. 
The message INDSY011 Dumping ... will appear. 


You will then be prompted to insert DUMPDATA.002 and 
DUMPDATA.008 diskettes if they were created. Insert them as 
requested. 


When the dump is completed, messages INDSY011 and INDSY012 
appear. Insert the system diskette and press any key to re-IPL. 


This completes the dump process. 


Using the Display Utility 


The display utility, INDDISP, resides on your customized utilities system 
diskette, and is used to display dumps of memory, trace buffers, and error 
counters. Note that to use the display utility, you must have previously 
taken a dump or issued the command INDSAVE, discussed below. 


To save dumps of trace buffers or error counters: 


L 


You must be in an active personal computer session. 
At the DOS prompt, type: 

INDSAVE TRACE 

or: 

INDSAVE COUNTER 


This action creates TRACE.DMP or COUNTER.DMP files on the 
diskette in the active drive, depending on the parameter you chose. 
This is a quick way to provide trace or error counter information 
without dumping the entire system. 
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Displaying the Dump 
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To display dumps, dumps of trace buffers, or dumps of error 
counters: 


1. You must be in an active personal computer session. 


2. At the DOS prompt, type: 


INDDISP a:DUMP 


or 


INDDISP b:DUMP 
3. Press Enter. 


4. The following message appears: 


INDDDOO4 Insert DUMPDATA.OO1. Press Enter, or End to 
quit 


5. Insert DUMPDATA.001 in the currently active drive you specified 
above and press Enter. 


6. Notice the display of the dump. It always begins at address 0000:0000. 
You can use the following keys: 
Home Takes you to another panel with additional options 
PgUp_ Takes you to the next higher 256 bytes of memory 
PgDn_ Takes you to the next lower 256 bytes of memory 
End Ends the use of this display utility | 


7. Ifyou press the Home key, a panel appears with prompts that allow you 
to display the following options: 


a. Trace buffer 


b. Registers at the time of the dump. If the registers are all zeros, they 
were not meaningful at the time of the dump. 


c. Error counters 
d. PC Presentation Space Work Areas 


e. PC Presentation Space Buffers. 


Dump Data Utilities 


Segment address in hexadecimal. Type the first four digits of the 
8-character address and press Enter. The following prompt appears: 


Enter offset to display 


Type the last four digits that follow the colon. Then that section of 
memory is displayed. 


The frequently used buffers listed in Figure E-1 may be found at the 
segment addresses indicated. 


Buffer You Type of PC Segment 

Want Displayed You Have Address 
DFT/CUT 3270 PC unique CE00 
communication hardware or 


buffers non-3270 PC 
hardware 


3270 PC unique 
hardware or 

non-3270 PC Mono 
Display hardware 


PC display buffer 


Non-3270 PC Color 
Display hardware 


3270 PC unique 
hardware 


PC graphics buffer 


Non-3270 PC 
hardware 


3270 PC unique 
hardware 


3270 display buffer A000 


Non-3270 PC 
hardware 


Not applicable 


* BIOS Modes 0 through 6 
** BIOS Modes D, E, 10, 11, and 18 


As described in the “TBM Enhanced Graphics Adapter” section of the Technical 
Reference Options and Adapter manual. 


Figure E-1. Frequently Used Trace Buffers 


Displaying the Error Counters 


To display the counter: 


1. 


2. 


You must be in an active personal computer session. 


At the DOS prompt, type: 


INDDISP COUNTER 


Press Enter. 
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4, The following message appears: 


INDDDOO6 Insert diskette with COUNTER.DMP. Press Enter, 
or End to quit 


Insert diskette with file COUNTER.DMP in the currently active drive, 
and press Enter. 


You will see a display of the counters where: 


RC Return code. 


TH = Threshold or the point at which the error-handling program 
takes action. 


CT = Count or the number of times this error has been reported to the 
error-handling program. 
SV = Severity level of error: 1, 2, 3.... 


Displaying the Trace Buffer 


To display the trace buffer: 


i 


2. 


You must be in an active personal computer session. 
At the DOS prompt, type: 

INDDISP TRACE 

Press Enter. The following message appears: 


INDDDOO5 Insert diskette with TRACE.DMP. Press Enter, or 
End to quit 


Insert the diskette with file TRACE.DMP in the currently active drive, 
and press Enter. 


You will see a display of the trace buffers. 


Using the Trace Command 


Trace is used in gathering data required to isolate the causes of software 
failures in the workstation program and is to be used during problem 
determination. If you encounter problems running Trace, refer to the JBM 
38270 Workstation Program Problem Determination Guide. 


The Trace command runs as a PC application and is used to turn Trace on 
and off. While running in IBM Personal Computer DOS application mode 
with the PC window active, the operator issues a Trace On command for 
the trace recordings he wants to start or a Trace Off command to stop all 
trace recording. The traces in effect are those specified on the most recent 
Trace On command. 


Trace Command 


The discussion of solving IBM 3270 Personal Computer problems in the 
IBM 3270 Workstation Program Problem Determination Guide identifies 
which events you must turn on to obtain the correct documentation for a 
given problem. 


The syntax of the command is: 


M on 0 |] .p 

ON n Gah p 

TRACE M n oll -p 
oFF [/d ] 


e The Trace commands may be typed and entered in any combination of 
uppercase and lowercase characters. 


e TRACE OFF /d turns off all trace requests and causes the error 
handler to take a dump. 


e One of each of the parameters shown in uppercase in a stack must be 
selected. 


e Lowercase parameters are optional. 


e M,n, o, and p represent decimal numbers corresponding to unique trace 
identification recording requests. 


e Single or multiple blanks and/or commas delineate individual requests. 
e The /d parameter indicates that a dump is desired. 


When a dump is requested, your system will request you to insert a 
diskette for the dump. This diskette will be formatted; therefore, all 
existing files on the diskette will be erased. After the dump gets 
control, the workstation program is no longer running. The only way 
to restart the system is by turning the system off and then on. 


Workstation Program Loading Procedure 


When the workstation program is [PLed, the INDCIPL.EXE loads the first 
system extension belonging to the workstation program, the supervisor, 
called INDSNUM.COM. Next, the INDCIPL.EXE loads the DOS subsystem 
extension INDSDOM.COM, followed by the remaining system extensions 
from low storage to high storage. When all the system extensions have 
been loaded, the DOS subsystem divides the rest of the remaining storage 
into the PC environments. The last PC environment gets all of the storage 
left over, which fits within the 640K address space. 
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Debugging a PC Application Program 


A PC application program running under the workstation program can be 
debugged by loading the application with the DEBUG utility, or any other 
software debugger that runs under the workstation program. You can use 
the debugger to help you find the errors in your PC application program. 


Debugging a System Extension 


Because system extensions do not have a logical refresh buffer, debugging 
your system extension can be done in the following ways: 


e You can use a hardware debugger. In this case you could code a stop 
condition in the beginning of the system extension to find out where it 
is loaded and debug the system extension from there. 


e You can run the system extension as a PC application and debug it 
using a software debugger. When the system extension is running 
correctly, you can remove any PC session dependencies such as DOS or 
BIOS calls. 


Control Blocks You Can Use during Debugging 


Following are some guidelines on how to find some of the contro! blocks 
used by the workstation program. These control blocks will assist you in 
debugging your system extension or PC application program. 


Warning: These offsets will change across releases. No 
coding dependencies should be implemented based on these 
offsets. 


Addresses are given in the format xx:yy, where xx is the segment portion of 
the address and yy is the offset portion of the address. 


Address 0:1E8 (interrupt vector X‘7A’) contains the address of INDKSY1, a 
module that belongs to the supervisor. The segment portion of that address 
is the beginning of the 3270 Workstation Program code. The first load 
module is named INDSNUM.COM. 


That address minus 5 points to the 1-word segment address of the 
supervisor’s data area. 
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The Supervisor’s Data Area 


The supervisor’s data area is on a segment boundary. All addresses within 
the supervisor’s data area are 16-bit addresses. They are offset addresses 
and are to be used with the segment address of the supervisor data area to 
refer to any address within the supervisor’s data area. 


Warning: These offsets will change across releases. No 
coding dependencies should be implemented based on these 
offsets. 


The supervisor’s data area is shown below. 


——» Supervisor Data Area 


OY 
+6BB Address of dispatcher data 
+7DB | Address of name table 


Area for priority 0 
Area for priority 1 
Area for priority 2 


Number of tasks 
1st TCB for that priority 


+C 


The Dispatcher’s Data Area 


To locate the dispatcher’s data area, use an offset of X‘671’ into the 
supervisor’s data segment. The first word in the dispatcher’s data area is 
an offset address of the dispatched active task’s task control block (TCB). 
The next word in the dispatcher’s data area contains the priority of the 
highest priority dispatchable task. Next are 65 four-byte areas, one for 
each of the 65 task priority levels, 0 through 64. In each 4-byte area, the 
first 2 bytes contain the number of dispatchable tasks at that priority. The 
next 2 bytes contain the offset address of the TCB for the first task in the 
round robin at that priority level. 
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Priority zero is reserved for the supervisor. The PC task that runs an 
application has a priority of 60. Tasks created by a PC application program 
are restricted to priority levels 36 through 64. 


Warning: These offsets will change across releases. No 
coding dependencies should be implemented based on these 
offsets. 


See Figure E-2 for offsets in previous releases. 


Release 2.1 | Release 3.0 | Release 4.0 


Figure E-2. Dispatcher Data Address Offsets 


The Task Control Block 


Warning: These offsets will change across releases. No 
coding dependencies should be implemented based on these 
offsets. 


The offset address of a TCB, used together with the supervisor’s data 
segment, can be used to locate that TCB. The fields of the TCB shown 
below may be helpful when you are debugging a program: 


+0 | TCB status byte 


+] | Wait byte 


+2 | Priority + 1 
+3 { Preemption type 
+4 | Stack address (ss/sp) 


+8 | Request queue head pointer 


+10] Request queue tail pointer 


+12 | Completion queue head pointer 


+14] Completion queue tail pointer 
+16 | Pointer to next TCB in round robin 
+18} SVC ID of task 
+24] Waiting for data from this FLQ ID 


+28 


ID of semaphore being waited on 
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The TCB Status Byte 


The TCB Wait Byte 
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The TCB status byte is formatted as follows: 


Bité 


Bit 0 — Task is waiting 

Bit 1 — Task is “unready” 

Bit 2 — Reserved 

Bit 3 — Task is nonpreemptable within the round robin or environment 
Bit 4 — Reserved 

Bit 5 — Reserved 

Bit 6 — Task is suspended 

Bit 7 — Reserved 


The TCB wait byte is formatted as follows: 
Request Comp | Comp | Sema- | Timer | Signal | Data | Reserved 
queue queue | signal | phore 


Bit 0 — Waiting for an RQE in the request queue 
Bit 1 — Waiting for an RQE in the completion queue 
Bit 2 — Waiting for a ‘completion’ signal 

Bit 3 — Waiting to for a ‘semaphore claimed’ signal 
Bit 4 — Waiting for a ‘timer tick’ signal 

Bit 5 — Waiting for a ‘generic’ signal 

Bit 6 — Waiting for a ‘data available’ signal 

Bit 7 — Reserved 


The TCB Preemption Type 


The TCB preemption type is specified as follows: 


e xX‘00’ — Task is preemptable 
e xX‘01’ — Task is nonpreemptable within round robin 
e X‘02’ — Task is nonpreemptable within environment 


The Request Queue Head Pointer 


The request queue head pointer points to the first request queue element 
(RQE) on the task’s request queue. The request queue tail pointer points to 
the last RQE on the task’s request queue. These RQEs were placed on the 
task’s request queue after the Make a Request supervisor service was 
requested to make a request of that task. These RQEs may not have been 
processed by the task yet, or the task may be currently working on 
processing one of the RQEs. When the task has finished processing an 
RQE, it will use the Reply to a Request service so that the supervisor will 
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either move the RQE from its request queue to the completion queue of the 
requesting task or discard the RQE if the requesting task did not want a 
reply. 


The Completion Queue Head Pointer 


The completion queue head pointer points to the first RQE on the task’s 
completion queue. The completion queue tail pointer points to the last 
RQE on the task’s completion queue. These RQEs were placed on the task’s 


_ completion queue as the result of a Make a Request service that had a reply 


type of “completion queue” specified. When the task requests the Get 
Request Completion service, the supervisor copies the contents of the RQE 
to the parameter list used for the service request, and returns the RQE to 
the system RQE pool. 


The Request Queue Element 


The following fields in an RQE may be helpful to you when you are 
debugging: 


RQE 
ID of requestor 


Next RQE on chain 


The ID should be the ID of a task or component that was created as part of 
your system extension or PC application program. This ID was returned to 
you when the Create Task Entry or Create Component Entry service 
request was completed. 


+0 


+2 


+4 


The Supervisor Name Table 
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Warning: These offsets will change across releases. No 
coding dependencies should be implemented based on these 
offsets. 


See Figure E-3 for offsets in previous releases. 


Release 2.1 | Release 3.0 | Release 4.0 


Figure E-3. Name Table Address Offsets 
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At offset X“78B’ into the supervisor’s data area is the pointer to the name 
table. The name table contains all the names in the system that were added 
to the table through the use of the supervisory objects services. Each name 
is followed by the index of the object that was created with that name. The 
name table has the following format: 


——+» Supervisor Data Area 


Address of dispatcher data 


Address of name table 


Name Table 


+7DB 


+A 


+C 


Following is a list of names used by the supervisor. Do not assign these 
same names to system objects that you create. 


Names that begin with the letters “IND” or 3270KS 
SYSKILL 
MEMORY 
DOSINT21 
DOSIOR 
DOSBADP 
XLATE 
SESSMGR 
KEYBOARD 
WSCTRL 
OIAM 
CPYUET 
MFIC 
3270EML 
PCPSM 
COPY 
BSMUET 


S 
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Presentation space represents the area that contains the data that is shown 
in an image on your display screen. The data is stored in a format that 
includes both the character to be displayed and information about how that 
character is to be displayed, called the attribute of the character. This 
appendix discusses attribute types, character codes, and presentation space 
sizes for DFT host, CUT host, notepad, and personal computer sessions on 
the IBM 3270 Personal Computer. 


Warning: Altering the contents of the presentation space 
can cause unpredictable results in the host application 
program that accesses the presentation space. Do not alter 
the contents of a host session presentation space unless the 
host application program is designed to interpret the changes 
that you make. 


Note: For information concerning presentation spaces that are defined to 
accept 3270 keystroke emulation, refer to Chapter 9, “Coding 3270 
Keystroke Emulation Service Requests.” 


Display images may be unformatted or formatted. An unformatted display 
is one that has no defined fields. A formatted display is one that has 
separate fields defined by the host application program. The first character 
position in each field contains a control character, or attribute, that defines 
the characteristics of that field. 


For detailed information on attributes and their use in the IBM 3270 data 
stream, see these manuals: 


e IBM 3270 Information Display System: 3274 Control Unit Description 
and Programmer’s Guide 


e IBM 3270 Information Display System: Data Stream Programmer’s 
Reference 


The IBM 3270 Personal Computer display station supports field attributes, 
extended field attributes, and character attributes. Field attributes are 
supported in CUT and DFT host sessions, and are used to define the start of 
a field and control the characteristics of that field. Character attributes 
are supported in CUT host sessions, DFT host sessions, and notepad 
sessions, and are used to control the attributes of a character. 


Note: If your DFT host session is customized to have an extended attributes 
buffer (EAB= Yes), the session will support field attributes, extended 
field attributes, and character attributes. Otherwise, the session 
supports only field attributes. 


Field Attributes 


Attributes 


The field attribute is used by the host application program to define the 
start of a field and to assign characteristics to that field. A field consists of 
the field attribute and all the data following it up to (but not including) the 
next field attribute. A field can wrap (continue) from the end of one row to 
the beginning of the next row within the presentation space. A field can 
also wrap from the last location in the presentation space to the first 
location. In any case, the field is terminated by the next field attribute. 
There is no limit to the number of fields that can be defined, other than 
that imposed by the screen size. 


The characteristics that can be assigned to a field are: 


e Protected or unprotected. A protected field is protected from 
modification by the operator. An unprotected field is available for the 
operator to enter or modify data. The unprotected definition classifies a 
field as an input field. 


e Alphanumeric or numeric. Subject to its being protected, an 
alphanumeric field is one into which an operator enters data normally, 
using the shift keys as required. 


When the numeric lock is active, fields defined as numeric will only 
accept characters 0 through 9,. , Dup, and-. Numeric lock can be 
overridden by pressing and holding the upshift key while typing. 
Overriding Numlock by this method will allow only upper shift 
characters to be entered. 


e Autoskip. A field defined as protected and numeric causes the cursor 
to skip to the next unprotected field. 


e Nondisplay or display/intensified display. The selected characteristics 
apply to the entire field. Nondisplay means that any characters entered 
from the keyboard are entered into the buffer for subsequent 
transmission to the application program but they are not displayed. 
Intensified display means the intensified characters appear on the 
screen brighter than the nonintensified characters. Some devices may 
not be able to intensify characters on the screen and will therefore 
highlight in a different manner. 


e Detectable or nondetectable. A field defined as detectable can be 
detected by the cursor select key (CrSel), subject to the use of a 
designator character. 


Figure F-1 shows the bit positions in the field attribute byte. Bit 0 is the 
leftmost bit in the byte, and bit 7 is the rightmost bit in the byte. 

Figure F-2 shows the bit assignments for the field attributes supported by 
the 3270 Personal Computer. 


. Upon entry of a character into the last character location of an unprotected 


data field, the cursor is repositioned based on the attributes of the next 
field. 
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If the field attribute defines the next field as (1) alphanumeric and either 
unprotected or protected, or (2) numeric and unprotected, the cursor skips 
the attribute character and is positioned to the first character location in 
that field. 


If the field attribute defines the field as numeric and protected, the cursor 
automatically skips that field and is positioned to the first character 
location of the next unprotected field. 


a eee ee 


Figure F-1. Field Attribute Bit Positions 


EBCDIC Bit | Field Characteristics 


11 = This byte is an attribute 


Unprotected 
Protected (see Note) 


Alphanumeric 

Numeric Gf numeric lock capability is activated, 
causes automatic numeric shift of keyboard) 
(see Note) 


00 
01 
10 
11 


Display not detectable by Cursor Select key 
Display detectable by Cursor Select key 
Intensified display detectable by Cursor Select key 
Nondisplay, nonprint, nondetectable 


Reserved — Always 0 


Modified data tag (MDT); identifies modified fields 
during Read Modified command operation 


0 = Field has not been modified 


1 = Field has been modified by the operator. Can also 


be set by a program in the data stream. 


Note: Bits 2 and 3 equal to binary 11 causes an automatic skip. 


Figure F-2. Field Attribute Bit Assignment 


Extended Field Attributes and Character Attributes 
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Extended field attributes and character attributes are used to give fields 
and single characters the attributes of highlighting, color, and character 
set. The extended field attribute is always associated with a field, and is 
positioned in the byte following the field attribute in the presentation 
space. The character attribute is associated with a single character, and is 
positioned in the byte following the character in the presentation space. 
The extended field attributes of any single character are always overridden 


Attributes 


by the character attributes associated with it. However, characters in 
nondisplay fields are never displayed. The attribute structure used for 
character attributes is the same as for extended field attributes. 


Figure F-3 shows the bit positions in the extended field/character attribute 
byte. Bit 0 is the leftmost bit in the byte, and bit 7 is the rightmost bit in 
the byte. Figure F-4 shows the bit assignments for the extended field 
attributes and character attributes supported by the IBM 3270 Personal 
Computer. 


Highlighting 
2 through 4 5 through 7 


Figure F-3. Extended Field Attribute and Character Attribute Bit 
Positions 


EBCDIC Bit | Character Characteristics 


Character highlighting: 
Normal! 

Blink 

Reverse video 
Underscore? 


how We tl 


2 through 4 Character color: 
000 = Default! 
001 = Blue 
010 = Red 
011 Pink 
100 = Green 


101 = Turquoise 
110 = Yellow 
111 = White 


5 through 7 Character set: 

000 = Base character set? 

001 = Reserved 

010 = Programmable Symbol Set A 
011 = Programmable Symbol Set B® 
100 = Programmable Symbol Set C3 
101 = Programmable Symbol Set D® 
110 = Programmable Symbol Set E? 
111 = Programmable Symbol Set F? 


low i i 


If this is a character attribute, a zero value in this field indicates that the value in the 
extended field attribute for this field is to be used. If this is an extended field attribute, a 
zero value in this field indicates that the default value for the display is to be used. 


2 On the Enhanced Graphics Adapter (EGA), the character highlighting underscore will be 
displayed as a norma! attribute. 


The Programmable Symbol Sets are not supported in notepad sessions on non-3270 PC 
hardware. 


Figure F-4. Extended Field Attribute and Character Attribute Bit 
Assignment 


For additional information on PC character attributes, see the IBM 
Personal Computer Technical Reference. 
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Presentation Space Character Tables 


Characters in the presentation space are represented by hexadecimal codes. 


Host and Notepad Session Character Codes 
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Figure F-5 shows the hexadecimal codes found in the DFT host, CUT host, 
and notepad presentation spaces, and the characters they represent. 
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1. Values X‘CO’ through X‘FF’ are used as attributes in CUT and DFT host 
sessions, and as characters in notepad sessions. 


2. Characters X‘68’ through X‘6F’ are replaced in the refresh buffer by 
X‘E8’, X69, X‘6A’, X‘F8’, X‘FE’, X‘D4’, X‘CE’, and X‘D3’, respectively. 
These characters are not used in the U.S.. 


Figure F-5. Host and Notepad Presentation Space Character Table 


Presentation Space Sizes 


Personal Computer Session Character Codes 


Figure F-6 shows the hexadecimal codes found in the personal computer 
presentation space, and the characters they represent. 
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Figure F-6. Personal Computer Presentation Space Character Table 
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For further information regarding the personal computer character set and 
attributes, refer to the IBM Personal Computer Technical Reference. 


Presentation Space Sizes 


Distributed Function Terminal (DFT) Host Presentation Space Sizes 


. Figure F-7 lists the presentation space size for DFT host sessions, based on 
the screen size and on whether the session is customized to support an 
extended attributes buffer (EAB). For additional information on color 
attributes, see the [BM Personal Computer Technical Reference. 
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! Presentation 

Attributes Space Size 
1920 characters No EAB (4-color) 1920 bytes 
(24 rows of 80 characters) 
1920 characters EAB (7-color) 3840 bytes 
(24 rows of 80 characters) 
2560 characters No EAB (4-color) 2560 bytes 
(82 rows of 80 characters) 
2560 characters EAB (7-color) 5120 bytes 
(82 rows of 80 characters) _ 
3440 characters No EAB (4-color) 3440 bytes 
(43 rows of 80 characters) 
3440 characters EAB (7-color) 6880 bytes 
(43 rows of 80 characters) 
3564 characters No EAB (4-color) 3564 bytes 
(27 rows of 1382 characters) 
3564 characters EAB (7-color) 7128 bytes 
(27 rows of 132 characters) 


Figure F-7. DFT Host Presentation Space Sizes 


Control Unit Terminal (CUT) Host Presentation Space Size 


The presentation space size for a CUT host session is 1920 bytes, one byte 
in the presentation space for each character position on the screen. 


Notepad Presentation Space Size 


The presentation space size for the notepad session depends on the 
configured size of the notepad session. Each character in the notepad 
session is represented by two bytes in the presentation space. The first byte 
representing a character is the character itself, and the second byte is the 
character attribute associated with the character. For example, a notepad 
defined to have 24 rows of 80 characters will have a presentation space of 
3840 bytes, since there can be 1920 characters in the notepad. 


Personal Computer Presentation Space Size 


F-8 


The presentation space size for the personal computer session is 4000 bytes. 
Each character in the personal computer session is represented by two 
bytes. The first byte representing a character is the character itself, and 


~ the second byte is the attribute associated with the character. 


Presentation Space Sizes 
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The DOS SETBLOCK Function Call 


Introduction 


Your application program can invoke the Save, Restore, Send, and Receive 
commands by using the DOS function calls SETBLOCK and EXEC. This 
appendix describes how to set up these DOS function calls in your 
application program. The DOS function calls are described in the DOS 
manuals that were shipped with the version of DOS you are using. 


The DOS SETBLOCK Function Call 


The DOS SETBLOCK function call modifies the number of allocated 
storage blocks. You use the SETBLOCK function to free all available 
storage other than the storage used by your application program, so that 
there is room for the Send, Receive, Save, or Restore .COM file. To call the 
SETBLOCK function, set up the registers as follows: 


AH = X‘4A’ 


BX = the amount of storage used by your application program (in 
paragraphs) . 


ES = the segment address of the block of storage used by your 
application program (that is, the segment address of the application 
program’s code segment). 


To determine the amount of storage used by your application program (in 
paragraphs), use the following formula: 


paragraphs = [ (program size + 15) / 16 ] 


Program size is the number of bytes shown for your .COM file in a directory 
listing obtained by the DOS DIR command, plus 16 paragraphs for the 
program segment prefix (PSP). If your application program allocates 
additional storage during execution, program size shouid include the 
number of bytes in the additional allocated storage as well. 


Note: Be sure that the SS:SP registers point to a stack area within the same 
block of storage as your program. 


Use the INT 21H instruction to invoke the DOS SETBLOCK function. 
For more information on the DOS SETBLOCK function and other DOS 


function calls, see the DOS manuals that were shipped with the version of 
DOS you are using. 


G-2 


The DOS EXEC Function Call 


The DOS EXEC Function Call 


The DOS EXEC function call loads and executes a program. You use the 
EXEC function to identify the program that you want to execute (Send, 
Receive, Save, or Restore), and to pass a parameter string to the program 
that contains the command line to be executed. To call the EXEC function, 
set up the registers as follows: 


AH = X‘4B’ 
AL = X‘00’ 
BX = offset address of the parameter block 


ES = segment address of the parameter block 


DX = offset address of an ASCIIZ string containing the drive, path, and 
file name of the program to be loaded 


DS = segment address of an ASCIIZ string containing the drive, path, 
and filename of the program to be loaded. 


The block pointed to by ES:BX has the following format: 


The Environment String 


The environment string is a series of ASCII strings (totaling less than 32K 
bytes) in the form: 


NAME = parameter 


Each string is terminated by a byte of zeros, and the entire set of strings is 
terminated by another byte of zeros. The environment built by the 
command processor (and passed to all programs it invokes) contains a 
COMSPEC =string at a minimum. The parameter on the COMSPEC string 
is the path used by DOS to locate the command processor on the disk. The 
last PATH and PROMPT command issued will also be in the environment, 
along with any environment strings entered through the DOS SET 
command. 


If you do not wish to change the environment string for the program being 


executed, set the segment address of the environment string to be passed to 
zero. Otherwise, build the new environment string and store the segment 
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The DOS EXEC Function Call 


address of the string in this word. Additional information on the 
environment string can be found in the DOS manuals that were shipped 
with the version of DOS you are using. 


The Command Line 


The command line contains any parameters that you wish to send to the 
program being executed. The format of the command line is as follows: 


Byte 0 is the number of bytes in the command line (a hexadecimal 
value). 


Byte 1 is the ASCII code for a space (X‘20’). 


The remaining bytes in the command line are the ASCII codes for the 
rest of the characters in the command line. 


The File Control Blocks 


The two default file control blocks (FCBs) are used to contain file names 
that may be needed by the program being executed. The format of the 
default FCBs is as follows: 


Byte 0 is a decimal number representing the drive, where 


e 00 represents the default drive 
e 01 represents drive A 
e (2 represents drive B 


e 03 represents drive C 


Bytes 1 through 8 contain the ASCII code for the file name, padded to 
the right with blanks if necessary. If a reserved drive name is placed 
here (such as LPT1), do not include the optional colon. 


Bytes 9 through 11 contain the ASCII code for the file name extension, 
padded to the right with blanks if necessary. The file name extension 
can be all blanks. Additional information on the format of the FCB can 
be found in the DOS manuals that were shipped with the version of 
DOS you are using. 


Use the INT 21H instruction to invoke the DOS EXEC function. 


Note: When control is returned to your application program, all registers are 
changed, including the stack. You must restore SS, SP, and any 
other required registers before proceeding. 


For more information on the DOS EXEC function and other DOS function 
calls, see the DOS manuals that were shipped with the version of DOS you 
are using. 


The DOS EXEC Function Call 
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Introduction 


Introduction 


This appendix contains explanations of the return codes issued by the 
workstation program. These return codes can appear in messages on the 
screen, or can be returned to your application program when it requests an 


API service. 


Return codes are two bytes long. The first byte of the return code is the 
function ID, and the second byte is the error number. The function ID 
indicates the portion of the workstation program that is issuing the return 
code. The error number indicates the specific condition being reported. 
The possible function IDs are: 


Function ID 


X‘12’ 
X‘13’ 
X‘22’ or X‘23’ 
X‘24’ or X‘25’ 
X ‘30’ 
X‘32? 
X ‘46’ 
X‘52’ 
X ‘62’ 
X ‘63’ 
X‘64’ 
X ‘69’ 
X‘6B’ 
X‘6C’ 
X‘6D’ 
X‘6E’ 
X‘72’ 
X‘7F’ 
X‘81’ 


Notes: 


Code Reported By 


Supervisor services 

Environment manager services 
Multiple DOS support services 
System Loader 

DFT system extension 

Host interactive services 

CUT system extension 

Notepad system extension 
Keyboard services 

Window management services 
Copy services 

Presentation space services 
Session information services 
Translate services 

Operator Information Area services 
3270 keystroke emulation services 
Error handler 

Dump task 

Enhanced Connectivity Router 


1. Return codes with a function ID of X‘Dx’ through X‘Fx’ are generated by 
user-supplied system extensions. Consult local documentation for the 
meaning of these return codes and the action to take when they are 
encountered. If you get any return codes that are not listed, use the 
procedures at your location for diagnosing the problem. 


2. “Local procedures,” to which you are frequently referred during this 
chapter, are the procedures followed in your location for isolating 
problems or making repairs. 


System Services Return Codes - 12xx 


Function [D X‘12’: System Services Return Codes 


Return codes beginning with function code X‘12’ indicate that an error 
occurred during supervisor operations, except return code X‘1200’, which 
indicates that the requested supervisor service was completed successfully. 


Code 
1200 


1201 


1202 


1203 


1204 


1205 


1206 


Explanation 


The requested supervisor 
service was completed 
successfully. 


The object being created 
does not have a unique 
name. 


The supervisor cannot 
create any more objects, 
because the SVC table is 
full; service failed. 


The supervisor cannot 
create any more named 
objects, because the 
system name table is full; 
service failed. 


The supervisor cannot 
create any more tasks, 
since it ran out of task 
control blocks; service 
failed. 


The SVC index specified 
in the DX register or the 
parameter list is not 
valid for the service 
requested. 


The specified priority 
was out of range; 
requested service failed. 


Action to Take 


None. 


Ensure that the name is unique. If it is, 
rerun the application that caused the 
error. If the error persists, follow local 
procedures and have the data available 
from “Return Code Error Steps” 1, 2, 
3c, 4, 5, and 6 on page H-57. 


You must increase the SVC table 
resource. See “Return Code Error 
Step” 8 on page H-57. 


You must increase the system name 
table resource. See “Return Code Error 
Step” 8 on page H-57. 


You must increase the number of task 
control blocks. See “Return Code Error 
Step” 8 on page H-57. 


Check the input parameters to the 
supervisor. Then check program logic 
and rerun the application. If the error 
persists, follow local procedures and 
have the data available from “Return 
Code Error Steps” 1, 2, 3c, 4, 5, and 6 on 
page H-57. 


Check the input priority index 
parameter to the supervisor. Then 
check program logic and rerun the 
application. If the error persists, follow 
local procedures and have the data 
available from “Return Code Error 
Steps” 1, 2, 3c, 4, 5, and 6 on page H-57. 
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H-4 


Code 


1207 


1208 


1209 


120A 


120B 


120D 


120E 


120F 


Explanation 


The requested reply is 
not valid; service failed. 


The requested wait is not 
valid; service failed. 


The queue is empty. 


The nonpreemption type 
specified on create task 
service is invalid, 
defaulted to preemptable; 
service successful. 


The system request 
queue element pool is 
depleted; the system 
cannot continue. 


A Release Semaphore 
request was issued for a 
semaphore that was 
already free. 


An invalid interrupt 
vector or level was 
specified; service failed. 


An invalid environment 
access was attempted; 
service failed. 


Action to Take 


Check the input parameters to the 
supervisor. Then check program logic 
and rerun the application. If the error 
persists, follow local procedures and 
have the data available from “Return 
Code Error Steps” 1, 2, 3c, 4, 5, and 6 on 
page H-57. 


Check the input parameters to the 
supervisor. Then check program logic 
and rerun the application. If the error 
persists, follow local procedures and 
have the data available from “Return 
Code Error Steps” 1, 2, 8c, 4, 5, and 6 on 
page H-57, 


Check the input parameters to the 
supervisor. Then check program logic 
and rerun the application. If the 
problem persists, follow local 
procedures and have the data available 
from “Return Code Error Steps” 1, 2, 
3c, 4, 5 and 6 on page H-57. 


Check the input parameters to the 
supervisor. Then check program logic 
and rerun the application. If the error 
persists, follow local procedures and 
have the data available from “Return 
Code Error Steps” 1, 2, 3c, 4, 5, and 6 on 
page H-57. 


You must increase the number of 
system RQEs. See “Return Code Error 
Step” 8 on page H-57. 


Follow local procedures and have the 
data available from “Return Code Error 
Steps” 1, 2, 3c, 4, 5 and 6 on page H-57. 


Check the input parameters to the 
supervisor. Check program logic and 
rerun the application. If the error 
persists, follow local procedures and 
have the data available from “Return 
Code Error Steps” 1, 2, 3c, 4, 5, and 6 on 
page H-57. 


Check the input parameters to the 
supervisor. Then check program logic 
and rerun the application. If the error 
persists, follow local procedures and 
have the data available from “Return 
Code Error Steps” 1, 2, 3c, 4, 5, and 6 on 
page H-57. 


Code 


1210 


1211 


1212 


1213 


1215 


1216 


121A 


System Services Return Codes - 12xx 


Explanation 


The timer is not owned 
by the requester; service 
failed. 


No more timers are 
available. 


A request was made to a 
terminating task; service 
failed. 


The dequeue request 
failed; the request is too 
big. 


The Install User Exit 
Table Entry service was 
requested with an entry 
index that is out of 
range. 


Invalid “count” 
parameter, which 
specifies the number of 
entries to be placed in a 
user exit table. 


The system is running 
with an XMA card. On 
Install User Exit Table 
Entry Service, the user 
exit table is in an 
address space that is not 
available to the 
requester. For more 
information on system 
extensions and the XMA 


card, see the Workstation 


Program Programming 
Guide. 


Action to Take 


Check the input parameter to the 
supervisor. Then check program logic 
and rerun the application. If the error 
persists, follow local procedures and 
have the data available from “Return 
Code Error Steps” 1, 2, 3c, 4, 5, and 6 on 
page H-57. 


You must increase the number of timer 
resources. See “Return Code Error 
Step” 8 on page H-57. 


Check the input parameters to the 
supervisor. Then check program logic 
and rerun the application. If the error 
persists, follow local procedures and 
have the data available from “Return 
Code Error Steps” 1, 2, 3c, 4, 5, and 6 on 
page H-57. 


Check the input parameters to the 
supervisor. Then check program logic 
and rerun the application. If the error 
persists, follow local procedures and 
have the data available from “Return 
Code Error Steps” 1, 2, 3c, 4, 5, and 6 on 
page H-57. 


Check the input parameters to the 
supervisor. Then check program logic 
and rerun the application. If the error 
persists, follow local procedures and 
have the data available from “Return 
Code Error Steps” 1, 2, 3c, 4, 5, and 6 on 
page H-57. 


Check the count parameter in the input 
parameter list to the supervisor. Then 
check program logic and rerun the 
application. If the error persists, follow 
local procedures and have the data 
available from “Return Code Error 
Steps” 1, 2, 3c, 4, 5, and 6 on page H-57. 


Check the input parameters to the 
supervisor. Then check program logic 
and rerun the application. If the error 
persists, follow local procedures and 
have the data available from “Return 
Code Error Steps” 1, 2, 3c, 4, 5, and 6 on 
page H-57. 
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Code 
121D 


121E 


121F 


1220 


1221 


1223 


1224 


1225 


1226 


Explanation 


There is sufficient 
memory for the 
supervisor to allocate 
requested resources. 


A first-level interrupt 
handler has run out of 
stacks. 


A version of PC Land is 
lower than 1.2. 


No more interrupt 
handlers can be 
installed. 


The environment ID 
specified in the DL 
register or the parameter 
list is not valid for the 
service requested. 


No free environment 
contro! blocks are 
available. 


The resource manager 
index specified in the 
request is invalid. 


The maximum number of 
resource managers was 
already defined. 


The maximum number of 
software interrupt 
vectors (32) were already 
taken. The mix of 
program applications is 
using too many software 
vectors for the 
supervisor to handle. 


Action to Take 


Check the SIF file resource requests. 
Correct any errors that exist, or if there 
are no errors, reduce the number of 
system extensions. 


Increase the number of stacks used by 
the first-level interrupt handler in the 
INDIBM2.S IF file. 


Warning: Increments of only 1 are 
advisable since each increment 
represents another 384 bytes. 


Use a version of the PC Land program 
higher than 1.2, or run Version 1.2 in 
redirector mode only. 


You must increase the number of 
interrupt handler resources. See return 
code error step 8. 


Check the environment ID input 
parameter to the supervisor. Then 
check program logic and rerun the 
application. If the error persists, follow 
local procedures and have the data 
available from “Return Code Error 
Steps” 1, 2, 3c, 4, 5, and 6 on page H-57. 


Follow local procedures and have the 
data available from “Return Code Error 
Steps” 1, 2, 3c, 4, 5, and 6 on page H-57. 


Check the input parameters to the 
supervisor. Then check program logic 
and rerun the application. If the error 
persists, follow local procedures and 
have the data available from “Return 
Code Error Steps” 1, 2, 3c, 4, 5, and 6 on 
page H-57. 


Check the input parameters to the 
supervisor. Then check program logic 
and rerun the application. If the error 
persists, follow local procedures and 
have the data available from “Return 
Code Error Steps” 1, 2, 3c, 4, 5, and 6 on 
page H-57. 


Stop any unnecessary applications to 
reduce the number of software interrupt 
vectors that are used. 


Code 


1228 


122B 


122C 


122D 


122K 


122F 


1230 


System Services Return Codes - 12xx 


Explanation 


The buffer provided on a 
Query Environment 
request was too small to 
contain the output; 
service failed. 


The environment already 
was suspended. 


The semaphore was not 
claimed, even though 
“wait for semaphore” 
was specified. (Some 
other specified wait 
condition was satisfied 
first.) 


The stoppable 
environment was not 
allowed to create 
environments. 


The name does not exist. 


The supervisor service 
does not exist. 


A task, fixed-length 
queue, or semaphore 
cannot be deleted if 
requests are pending. 


Action to Take 


Check the input parameter to the 
supervisor. Then check program logic 
and rerun the application. If the error 
persists, follow local procedures and 
have the data available from “Return 
Code Error Steps” 1, 2, 3c, 4, 5 and 6 on 
page H-57. 


Check the input parameters to the 
supervisor. Then check program logic 
and rerun the application. If the error 
persists, follow local procedures and 
have the data available from “Return 
Code Error Steps” 1, 2, 3c, 4, 5 and 6 on 
page H-57. 


Check the input parameters to the 
supervisor. Then check program logic 
and rerun the application. If the error 
persists, follow local procedures and 
have the data available from “Return 
Code Error Steps” 1, 2, 3c, 4, 5 and 6 on 
page H-57. 


Check the input parameters to the 
supervisor. Then check program logic 
and rerun the application. If the error 
persists, follow local procedures and 
have the data available from “Return 
Code Error Steps” 1, 2, 3c, 4, 5 and 6 on 
page H-57. 


Check the input parameters to the 
supervisor. Then check program logic 
and rerun the application. If the error 
persists, follow local procedures and 
have the data available from “Return 
Code Error Steps” 1, 2, 3c, 4, 5 and 6 on 
page H-57. 


Check the input parameters to the 
supervisor. Then check program logic 
and rerun the application. If the error 
persists, follow local procedures and 
have the data available from “Return 
Code Error Steps” 1, 2, 3c, 4, 5 and 6 on 
page H-57. 


Check the input parameters to the 
supervisor. Then check program logic 
and rerun the application. If the error 
persists, follow local procedures and 
have the data available from “Return 
Code Error Steps” 1, 2, 3c, 4, 5 and 6 on 
page H-57. 
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Code 


1231 


1232 


1233 


1234 


1235 


1236 


1237 


Explanation 


The task cannot be 
deleted, because it owns 
a timer. 


The supervisor cannot 
stop or delete a 
nonstoppable 
environment. - 


The supervisor cannot 
find the specified 
resource. 


The object to be installed 
in a gate is not a task or 
component, the gate 
length is invalid, or an 
invalid index (service 
number) was specified in 
the AL register on 
request. 


A user exit table cannot 
be created with a length 
of zero. 


No request queue 
elements are on the 
request queue. 


The dequeue with no 
wait failed because it is 
not the requester’s turn. 


Action to Take 


Check the input parameters to the 
supervisor. Then check program logic 
and rerun the application. If the error 
persists, follow local procedures and 
have the data available from “Return 
Code Error Steps” 1, 2, 3c, 4, 5 and 6 on 
page H-57. 


Check the input parameters to the 
supervisor. Then check program logic 
and rerun the application. If the error 
persists, follow local procedures and 
have the data available from “Return 
Code Error Steps” 1, 2, 3c, 4, 5 and 6 on 
page H-57. 


Check the input parameters to the 
supervisor. Then check program logic 
and rerun the application. If the error 
persists, follow local procedures and 
have the data available from “Return 
Code Error Steps” 1, 2, 3c, 4, 5 and 6 on 
page H-57. 


Check the input parameters to the 
supervisor. Then check program logic 
and rerun the application. If the error 
persists, follow local procedures and 
have the data available from “Return 
Code Error Steps” 1, 2, 3c, 4, 5 and 6 on 
page H-57. 


Correct the length and retry. 


Check the input parameters to the 
supervisor. Then check program logic 
and rerun the application. If the error 
persists, follow local procedures and 
have the data available from “Return 
Code Error Steps” 1, 2, 8c, 4, 5 and 6 on 
page H-57. 


Check the input parameters to the 
supervisor. Then check program logic 
and rerun the application. If the error 
persists, follow local procedures and 
have the data available from “Return 
Code Error Steps” 1, 2, 3c, 4, 5 and 6 on 
page H-57. 


Code 


1238 


1239 


123A 


123B 


123C 


123D 


123F 


System Services Return Codes - 12xx 


Explanation 


There is an error in 
opening a file. 


There is not enough 
room in the fixed-length 
queue to enqueue the 
specified data. 


There is an error reading 
in a file. 


The supervisor cannot 
create any more gates, 
because the system gate 
table is full. 


The type specified is not 
a valid semaphore type. 


This code was returned 
on a claim semaphore 
with a no-wait; it means 
that the semaphore is 
already claimed. 


The gates cannot be 
deleted. 


Action to Take 


Check the first message on the screen 
for the name of the file. Verify that the 
file exists on your system diskette. If 
the error persists, follow local 
procedures and have the data available 
from “Return Code Error Steps” 1, 2, 6, 
and 7 on page H-57. 


Check the input parameters to the 
supervisor. Then check program logic 
and rerun the application. If the error 
persists, follow local procedures and 
have the data available from “Return 
Code Error Steps” 1, 2, 3c, 4, 5 and 6 on 
page H-57. 


Check the first message on the screen 
for the name of the file. Verify that the 
file has not been damaged on your 
system diskette. (Follow the procedures 
in your DOS manual to run a Check 
Disk.) If there is damage, customize 
again on a new formatted diskette. If 
the error persists, follow local 
procedures and have the data available 
from “Return Code Error Steps” 1, 2, 6, 
and 7 on page H-57. 


Increase the gate table size. See 
“Return Code Error Step” 8 on page 
H-57. 


Check the input parameters to the 
supervisor. Then check program logic 
and rerun the application. If the error 
persists, follow local procedures and 
have the data available from “Return 
Code Error Steps” 1, 2, 3c, 4, 5 and 6 on 
page H-57. 


Check the program logic. Correct the 
wait status if needed, and rerun the 
application. If the error persists, follow 
local procedures and have the data 
available from “Return Code Error 
Steps” 1, 2, 3c, 4, 5, and 6 on page H-57. 


Check the input parameters to the 
supervisor. Then check program logic 
and rerun the application. If the error 
persists, follow local procedures and 
have the data available from “Return 
Code Error Steps” 1, 2, 3c, 4, 5 and 6 on 
page H-57. 
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Code Explanation 


1240 The delete environment 
is already pending. 


1241 The fixed length queue 
size is in error. 


H-10 


Action to Take 


Check the input parameters to the 
supervisor. Then check program logic 
and rerun the application. If the error 
persists, follow local procedures and 
have the data available from “Return 
Code Error Steps” 1, 2, 3c, 4, 5 and 6 on 
page H-57. 


Check the input parameters to the 
supervisor. Then check program logic 
and rerun the application. If the error 
persists, follow local procedures and 
have the data available from “Return 
Code Error Steps” 1, 2, 3c, 4, 5 and 6 on 
page H-57. 


Environment Manager Services Return Codes - 13xx 


Function ID X‘13’: Environment Manager Services 


Return Codes 


Return codes beginning with function code X‘13’ indicate that an error 
occurred during environment manager operations, except return code 
X‘1300’, which indicates that the requested environment manager service 
was completed successfully. 


Code 
1300 


1305 


1306 


130C 


130F 


Explanation 


The requested 
environment manager 
service was completed 
successfully. 


The SVC index specified 
in the DX register or the 
parameter list is not 
valid for the service 
requested. 


The priority specified is 
not in the range of valid 
priorities. 


A request to stop, reset, 
suspend, or resume an 
environment failed 
because the return code 
field in the parameter 
list of the work request 
was not set to zero. 


The requester is not 
allowed to complete the 
type of request that was 
made, because of invalid 
environment access. 


Action to Take 


None. 


Check the input parameters to the 
supervisor. Then check program logic 
and rerun the application. If the error 
persists, follow local procedures and 
have the data available from “Return 
Code Error Steps” 1, 2, 3c, 4, 5 and 6 on 
page H-57. 


Check the input parameters to the 
supervisor. Then check program logic 
and rerun the application. If the error 
persists, follow local procedures and 
have the data available from “Return 
Code Error Steps” 1, 2, 3c, 4, 5 and 6 on 
page H-57. 


Set the return code field of the input 
parameter list to zero. Then rerun the 
application. If the error persists, follow 
local procedures and have the data 
available from “Return Code Error 
Steps” 1, 2, 3c, 4, 5, and 6 on page H-57. 


Check to be sure the requester is 
allowed to complete the specified 
request. Then check the input 
parameters to the supervisor, check 
program logic, and rerun the 
application. If the error persists, follow 
local procedures and have the data 
available from “Return Code Error 
Steps” 1, 2, 3c, 4, 5, and 6 on page H-57. 


Appendix H. Return Codes H-11 


Environment Manager Services Return Codes - 13xx 


H-12 


Code 


1314 


1317 


1321 


1322 


1323 


Explanation 


A request was made toa 
task in an environment 
that was stopped, reset, 
or involved in an 
INDSPLIT or 
INDMERGE operation 
before the request could 
be acted upon. 


The requester is in a 
stoppable environment 
and is trying to stop, 
suspend, or resume 
another environment. 


The environment ID 
specified in the DL 
register or the parameter 
list is not valid for the 
service requested. 


An attempt to stop a 
personal computer 
environment that was 
made either through the 
API by using 
ALT-CTRL-DEL or by a 
request to delete an 
environment (using 
INDSPLIT or 
INDMERGE) failed 
because some resources 
were not successfully 
released. Some internal 
error occurred, and the 
stop is not recoverable. 


No free environment 
control blocks are 
available. 


Action to Take 


Once the stop, reset, INDSPLIT, or 
INDMERGE is completed, the 
parameter list can be set up and the 
request made again. If the request was 
not made by an application and no 
error can be found in your procedures, 
check the input parameters to the 
supervisor. Then check program logic 
and rerun the application. If the error 
persists, follow local procedures and 
have the data available from “Return 
Code Error Steps” 1, 2, 3a, 4, 5, and 6 
on page H-57. 


Check that the requester is allowed to 
complete the specified request. Check 
the input parameters to the supervisor. 
Check program logic and rerun the 
application. If the error persists, follow 
local procedures and have the data 
available from “Return Code Error 
Steps” 1, 2, 3a, 4, 5, and 6 on page H-57. 


Check the environment ID input 
parameters to the supervisor. Then 
check program logic and rerun the 
application. If the error persists, follow 
local procedures and have the data 
available from “Return Code Error 
Steps” 1, 2, 3c, 4, 5, and 6 on page H-57. 


The environment on which the stop was 
not completed cannot be used. It may be 
that a system error has occurred or that 
some resource manager or its device 
has hung. In this case, you may want to 
turn power off and on again. If no error 
can be found in your procedures, follow 
local procedures and have the data 
available from “Return Code Error 


NINA 


Steps” 1, 2, 3a, 4, 5 and 6 on page H-57. 


Follow local procedures and have the 
data available from “Return Code Error 
Steps” 1, 2, 3c, 4, 5, and 6 on page H-5’7. 


Environment Manager Services Return Codes - 13xx 


Code 


1324 


1325 


1327 


1328 


Explanation 


The resource manager 
index specified in the 
request is invalid. 


A Resource Manager 
Open request failed 
because no resource 
manager indexes are 
available. 


An attempt to stop a 
personal computer 
environment that was 
made either through the 
API by using 
ALT-CTRL-DEL or by a 
request to delete an 
environment (using 
INDSPLIT or 
INDMERGE) failed 
because the process took 
too long to complete. The 
request may be 
completed at a later 
time. 


The size of the output 
buffer specified in a 
Query Environment 
Characteristics request 
is too small to hold the 
data requested. 


Action to Take 


Check the input parameters to the 
supervisor. Then check program logic 
and rerun the application. If the error 
persists, follow local procedures and 
have the data available from “Return 
Code Error Steps” 1, 2, 3c, 4, 5, and 6 on 
page H-57. 


Increase the number of resource 
managers. See return code error step 8. 


The environment in which the stop 
request was not completed cannot be 
used. If possible, wait until the 
condition clears. If it does not clear, 
another environment may be taking too 
much processor time, so that this stop 
request cannot be completed. You may 
reduce the system load by stopping 
another environment. If the condition 
does not clear, a system error may have 
occurred or some resource manager or 
its device has hung. In this case, you 
may want to turn power off/on again. If 
power off/on is not attempted, the 
system will continue to try to clean up. 
If the cleanup is completed, the 
environment manager will post a 
different return code, and the 
environment may be reused. If the 
cleanup is not completed, follow local 
procedures and have the data available 
from “Return Code Error Steps” 1, 2, 
3a, 4, 5, and 6 on page H-57. 


Some common reasons that an 
environment cleanup will not be 
completed: 


e The application is still holding a 
code serialization semaphore. 

e The cleanup component did not 
delete all its resources. 

e A task in the environment being 
cleaned up is waiting for a reply to 
a request from a system extension. 


Check the input parameters to the 
supervisor. Then check program logic 
and rerun the application. If the error 
persists, follow local procedures and 
have the data available from “Return 
Code Error Steps” 1, 2, 3c, 4, 5, and 6 on 
page H-57. 


Appendix H. Return Codes H-13 


Environment Manager Services Return Codes - 13xx 


H-14 


Code 
1329 


182D 


1332 


1333 


1340 


Explanation 


A request was made to 
resume an environment 
that was not ina 
suspended state. 


A request was made to 
create an environment, 
but the requester is in a 
stoppable environment. 


A request was made to 
stop a nonstoppable 
system environment. 


A request to move a 
resource to the top of a 
resource chain or to 
delete a resource from a 
resource chain failed 
because the resource 
specified could not be 
found. 


A previous request to 
delete the specified 
environment using 
INDSPLIT or 
INDMERGE is already 


in progress. 


Action to Take 


Check the input parameters to the 
supervisor. Then check program logic 
and rerun the application. If the error 
persists, follow local procedures and 
have the data available from “Return 
Code Error Steps” 1, 2, 3b, 4, 5, and 6 
on page H-57. 


Check the input parameters to the 
supervisor. Then check program logic 
and rerun the application. If the error 
persists, follow local procedures and 
have the data available from “Return 
Code Error Steps” 1, 2, 3c, 4, 5, and 6 on 
page H-57. 


Check the input parameters to the 
supervisor. Then check program logic 
and rerun the application. If the error 
persists, follow local procedures and 
have the data available from “Return 
Code Error Steps” 1, 2, 3a, 4, 5, and 6 
on page H-57. 


Check the input parameters to the 
supervisor. Then check program logic 
and rerun the application. If the error 
persists, follow local procedures and 
have the data available from “Return 
Code Error Steps” 1, 2, 3c, 4, 5, and 6 on 
page H-57. 


Check the input parameters to the 
supervisor. Then check program logic 
and rerun the application. If the error 
persists, follow local procedures and 
have the data available from “Return 
Code Error Steps” 1, 2, 3a, 4, 5, and 6 
on page H-57. 


Environment Manager Services Return Codes - 13xx 


Code 


1342 


1343 


Explanation 


A previous request to 
stop an environment 
made through the API by 
using ALT-CTRL-DEL or 
by a previous request to 
delete an environment 
(using INDSPLIT or 
INDMERGE) failed with 
a return code of X‘1327’, 
indicating a time-out has 
occurred. That request 
is now completed, and 
the environment is now 
available for reuse. 


A request to stop, reset, 
suspend, or resume an 
environment failed 
because the request type 
field in the parameter 
list was not a valid 
request type. 


Action to Take 


Make the window active that 
previously returned the error, and 
begin another application. 


Check the input parameters to the 
supervisor, including the values in the 
parameter list. Then check program 
logic and rerun the application. If the 
error persists, follow local procedures 
and have the data available from 
“Return Code Error Steps” 1, 2, 3c, 4, 5 
and 6 on page H-57. 


Appendix H. Return Codes H-15 


DOS Subsystem Services Return Codes - 22xx or 23xx 


Function ID X‘22’ or X‘23’: DOS Subsystem Services 


Return Codes 


Return codes beginning with function code X‘22’ or X‘23’ indicate that an 
error occurred during DOS subsystem operations, except return code 
X‘2200’, which indicates that the requested DOS subsystem service was 
completed successfully. In some cases, the return code indicates that the 
error was generated by DOS when the DOS subsystem issued a DOS 
function call. 


Code 


2200 


2201 
or 
2301 


2202 
or 
2302 


2203 
or 
2303 


2204 
or 
2304 


2205 
or 
2305 


Explanation 


The requested DOS 
subsystem service was 
completed successfully. 


The DOS subsystem 
issued a DOS interrupt 
X‘21’ function call, and 
DOS failed the request 
with DOS ERROR CODE 
1. INVALID FUNCTION 
NUMBER. 


The DOS subsystem 
issued a DOS interrupt 
X‘21’ function call, and 
DOS failed the request 
with DOS ERROR CODE 
2. FILE NOT FOUND. 


The DOS subsystem 
issued a DOS interrupt 
X‘21’ function call, and 
DOS failed the request 
with DOS ERROR CODE 
3. PATH NOT FOUND. 


The DOS subsystem 
issued a DOS interrupt 
X‘21’ function call, and 
DOS failed the request 
with DOS ERROR CODE 
4, TOO MANY OPEN 
FILES (NO HANDLES 
LEFT). 


The DOS subsystem 
issued a DOS interrupt 
X‘21’ function call, and 
DOS failed the request 
with DOS ERROR CODE 
5. ACCESS DENIED. 


Action to Take 


None. 


Follow local procedures and have the 
data available from “Return Code Error 
Steps” 1, 2, 4, 5, and 6 on page H-57. 


Place the file that could not be found 
on the disk being used and retry the 
operation. If the error persists, follow 
local procedures and have the data 
available from “Return Code Error 
Steps” 1, 2, 4, 5, and 6 on page H-57. 


Place a disk in the drive with the 
correct path or create the path on the 
disk and then retry the operation. If the 
error persists, follow local procedures 
and have the data available from 
“Return Code Error Steps” 1, 2, 4, 5, 
and 6 on page H-57. 


Create a CONFIG.SYS on the IPL disk 
or edit the existing one and increase 
the number of file handles. The 
command in the file is FILES = xx, 
where xx is the number of file handles. 
See the DOS manual for details on 
setting up your CONFIG.SYS file. If the 
error persists, follow local procedures 
and have the data available from 
“Return Code Error Steps” 1, 2, 4, 5, 
and 6 on page H-57. 


Follow local procedures and have the 
data available from “Return Code Error 
Steps” 1, 2 4, 5, and 6 on page H-57.his 
chapter. 


H-16 


DOS Subsystem Services Return Codes - 22xx or 23xx 


Code 
2206 


or 
2306 


2207 
or 
2307 


2208 


or 
2308 


2209 
or 
2309 


220A 
or 
230A 


220B 
or 
230B 


220C 
or 
230C 


Explanation 


The DOS subsystem 
issued a DOS interrupt 
X‘21’ function call, and 
DOS failed the request 
with DOS ERROR CODE 
6. INVALID HANDLE. 


The DOS subsystem 
issued a DOS interrupt 
X‘21’ function call, and 
DOS failed the request 
with DOS ERROR CODE 
7. MEMORY CONTROL 
BLOCKS DESTROYED. 


The DOS subsystem 
issued a DOS interrupt 
X‘21’ function call, and 
DOS failed the request 
with DOS ERROR CODE 
8. INSUFFICIENT 
MEMORY. 


The DOS subsystem 
issued a DOS interrupt 
X‘21’ function call, and 
DOS failed the request 
with DOS ERROR CODE 
9. INVALID MEMORY 
BLOCK ADDRESS. 


The DOS subsystem 
issued a DOS interrupt 
X‘21’ function call, and 
DOS failed the request 
with DOS ERROR CODE 
10. INVALID 
ENVIRONMENT. 


The DOS subsystem 
issued a DOS interrupt 
X‘21’ function call, and 
DOS failed the request 
with DOS ERROR CODE 
11. INVALID FORMAT. 


The DOS subsystem 
issued a DOS interrupt 
X‘21’ function call, and 
DOS failed the request 
with DOS ERROR CODE 
12. INVALID ACCESS 
CODE. 


Action to Take 


Follow local procedures and have the 
data available from “Return Code Error 
Steps” 1, 2 4, 5, and 6 on page H-57. 


Follow local procedures and have the 
data available from “Return Code Error 
Steps” 1, 2, 4, 5 and 6 on page H-57. 


Make more storage available and retry 
the request. If it appears that there 
should have been enough storage, 
follow local procedures and have the 
data available from “Return Code Error 
Steps” 1, 2, 4, 5, and 6 on page H-57. 


Follow local procedures and have the 
data available from “Return Code Error 
Steps” 1, 2, 4, 5 and 6 on page H-57. 


Follow local procedures and have the 
data available from “Return Code Error 
Steps” 1, 2, 4, 5 and 6 on page H-57. 


Follow local procedures and have the 
data available from “Return Code Error 
Steps” 1, 2, 4, 5 and 6 on page H-57. 


Follow local procedures and have the 
data available from “Return Code Error 
Steps” 1, 2, 4, 5 and 6 on page H-57. 


Appendix H. Return Codes H-17 


DOS Subsystem Services Return Codes - 22xx or 23xx 


H-18 


Code 


220D © 


or 
230D 


220F 
or 
230F 


2210 
or 
2310 


2211 
or 
2311 


2212 
or 
2312 


2213 
thru 
2253 
or 
2313 
thru 
2353 


Explanation 


The DOS subsystem 
issued a DOS interrupt 
X‘21’ function call, and 
DOS failed the request 
with DOS ERROR CODE 
13. INVALID DATA. 


The DOS subsystem 
issued a DOS interrupt 
X‘21’ function call, and 
DOS failed the request 
with DOS ERROR CODE 
15. INVALID DRIVE 
WAS SPECIFIED. 


The DOS subsystem 
issued a DOS interrupt 
X‘21’ function call, and 
DOS failed the request 
with DOS ERROR CODE 
16. ATTEMPT TO 
REMOVE THE 
CURRENT 
DIRECTORY. 


The DOS subsystem 
issued a DOS interrupt 
X‘21’ function call, and 
DOS failed the request 
with DOS ERROR CODE 


17. NOT SAME DEVICE. 


The DOS subsystem 
issued a DOS interrupt 
X‘21’ function call, and 
DOS failed the request 
with DOS ERROR CODE 
18. NO MORE FILES. 


The DOS subsystem 
issued a DOS interrupt 
X‘21’ function call, and 
DOS failed the request 
with a DOS ERROR 
CODE nn, where nn is in 
hexadecimal. 


Action to Take 


Follow local procedures and have the 
data available from “Return Code Error 


Steps” 1, 2, 4, 5 and 6 on page H-57. 


chapter. 


Follow local procedures and have the 
data available from “Return Code Error 
Steps” 1, 2, 4, 5 and 6 on page H-57. 


Follow local procedures and have the 
data available from “Return Code Error 
Steps” 1, 2, 4, 5 and 6 on page H-57. 


Follow local procedures and have the 
data available from “Return Code Error 
Steps” 1, 2, 4, 5 and 6 on page H-57. 


Follow local procedures and have the 
data available from “Return Code Error 
Steps” 1, 2, 4, 5 and 6 on page H-57. 


Follow local procedures and have the 
data available from “Return Code Error 
Steps” 1, 2, 4, 5 and 6 on page H-57. 


DOS Subsystem Services Return Codes - 22xx or 23xx 


Code 
22K2 


22E3 


22K4 


Explanation 


An error occurred in the 
DOS subsystem. A Split 
or Merge command was 
rejected, because it was 
issued for an 
environment that does 
not exist. 


An error occurred in the 
DOS subsystem. A Split 
or Merge command was 
rejected, because it was 
issued for an 
environment that is 
being terminated. 


An error occurred in the 
DOS subsystem when the 
DOS environment task 
received an invalid 
request. The only valid 
requests are “Create” 
and “Clean Up.” 


Action to Take 


Issue a Display Environment 
C(NDDENV *) command to see what 
environments do exist. If it appears 
that the Split command should have 
been completed, take a system dump by 
pressing Alt + Ctrl + Test (Alt + Ctrl 
+ Scroll Lock on an enhanced PC 
keyboard, Alt + Ctrl + {+} on an XT 
or AT keyboard), then follow your local 
procedures and have available the 
dump and the data from “Return Code 
Error Steps” 2 and 6 on page H-57. 


Wait until the original Split command 
is completed. If it hangs, take a system 
dump by pressing Alt + Ctr] + Test 
(Alt + Ctrl + Scroll Lock on an 
enhanced PC keyboard, Alt + Ctrl + 
{+} on an XT or AT keyboard), then 
follow your local procedures and have 
available the dump and the data from 
“Return Code Error Steps” 2 and 6 on 
page H-57. 


If the problem can be re-created, follow 
your local procedures and have 
available the dump and the data from 
“Return Code Error Steps” 1, 2, 3c, 4, 5, 
and 6 on page H-57. 


If the problem cannot be re-created, 
take a system dump by pressing Alt + 
Ctrl + Test (Alt + Ctrl + Scroll Lock 
on an enhanced PC keyboard, Alt + 
Ctrl + {+} on an XT or AT keyboard), 
then follow your local procedures and 
have available the dump and the data 
from “Return Code Error Steps” 2 and 6 
on page H-57. 
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DOS Subsystem Services Return Codes - 22xx or 23xx 


H-20 


Code 


22E5 


22K6 


22E7 


22K8 


Explanation 


An error occurred in the 
DOS subsystem when the 
DOS environment task 
received an invalid 
parameter list. The 
return code field of the 
input parameter list was 
nonzero. 


An error occurred in the 
DOS subsystem when the 
DOS Query Environment 
request received an 
invalid parameter list. 
The return code field of 
the input parameter list 
was nonzero. 


A request was made with 
an invalid environment 
ID. A DOS Query 
Environment request 
was issued for an 
environment that does 
not exist, or a memory 
request was issued for an 
invalid environment. 


An error occurred in the 
DOS subsystem. A 
Create Environment 
request was issued that 
was not completed. 


Action to Take 


Ensure that the parameter list passed to 
the DOS environment task has a zero 
return code field. If the problem 
persists, follow your local procedures 
and have available the dump and the 
data from “Return Code Error Steps” 1, 
2, 3c, 4, 5, and 6 on page H-57. 


If the problem cannot be recreated, take 
a system dump by pressing Alt + Ctrl 

+ Test (Alt + Ctrl + Scroll Lock on 
an enhanced PC keyboard, Alt + Ctrl 
+ {+} on an XT or AT keyboard), then 
follow your local procedures and have 
available the dump and the data from 
“Return Code Error Steps” 2 and 6 on 
page H-57. 


Ensure the parameter list passed to 
DOS Query Environment has a zero 
return code field. If the problem 
persists, follow your local procedures 
and have available the dump and the 
data from “Return Code Error Steps” 1, 
2, 8c, 4, 5, and 6 on page H-57. 


If the problem cannot be recreated, take 
a system dump by pressing Alt + Ctrl 
+ Test (Alt + Ctrl + Scroll Lock on 
an enhanced PC keyboard, Alt + Ctrl 
+ {+} on an XT or AT keyboard), then 
follow your local procedures and have 
available the dump and the data from 
“Return Code Error Steps” 2 and 6 on 
page H-57. 


Issue a Display Environment 
(INDDENV ) command to see what 
environments do exist. If it seems that 
the Environment request should have 
been completed successfully, follow 
local procedures and have available the 
dump and the data from “Return Code 
Error Steps” 1, 2, 3c, 4, 5, and 6 on page 
H-57. 


This return code is always accompanied 
by a second return code (XXXX) that 
explains why the Create Environment 
request failed. Look up the second 
return code and take the action 
recommended for that return code. 


DOS Subsystem Services Return Codes - 22xx or 23xx 


Code 
23FD 


23FE 


23FF 


Explanation 


A request was made 
using the Asynchronous 
DOS Function Request 
service without a prior 
request to connect for 
asynchronous DOS 
function requests. 


The request to the DOS 
subsystem to add a 
device to the DOS 
subsystem redirection 
function failed. 


The DOS subsystem 
encountered an error 
while processing a 
request for a personal 
computer session for 
which there is no way to 
report the error to the 
application. The 
environment in which 
the application was 
running stopped. 


Action to Take 


Request the Asynchronous DOS 
Function Request service with a 
request type of X‘00’ to connect for 
asynchronous DOS function requests. 


Run fewer programs that are adding 
entries into the redirection tables. 
Re-IPL to reset the DOS subsystem and 
retry the request. If the error persists, 
follow local procedures and have the 
data available from “Return Code Error 
Steps” 1, 2, 4, 5, and 6 on page H-57. 


This return code is always accompanied 
by a second return code (XXXX) that 
explains what the initial failure was. 
Look up the second return code and 
take the action recommended for that 
return code. Correct the problem in the 
application or system and retry the 
application. If the error persists, follow 
local procedures and have the data 
available from “Return Code Error 
Steps” 1, 2, 4, 5, and 6 on page H-57. 
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System Loader Return Codes - 24xx or 25xx 


Function IDs X‘24’ or X‘25’: System Loader Return 


Codes 


Return codes beginning with function code X‘24’ or X‘25’ indicate that an 
error occurred during system loader operations. 


Code Explanation 


2404 A request was made to 
the loader for storage to 
be allocated from the 
XMA card and assigned 
to a bank. This return 
code indicates there were 
no available banks. 

2405 A request was made to 
the loader for storage to 
be allocated from the 
XMA card and assigned 
to a bank. This return 
code indicates that the 
requested storage size 
was invalid. 

2406 A request was made to 
the loader for storage to 
be allocated from the 
XMA card and assigned 
to a bank. This return 
code indicates that there 
was not enough storage 
available on the XMA 
card. 


A 22K8 preceding the 
2406 return code 
indicates that the 
workstation program ran 
out of XMA storage 
while trying to create a 
PC session. For 
example, you may 
receive 22E82406 if you 
customized the system 
for a 2-megabyte card 
and ran the system with 
a 1-megabyte card; or if 
you customized for 
multiple PC sessions, 
there may not be enough 
storage for the last 
session if you have 
device drivers and user 
system extensions. 


H-22 


Action to Take 


Follow local procedures and have the 
data available from “Return Code Error 
Steps” 1, 2, 4, and 7 on page H-57. 


Follow local procedures and have the 
data available from “Return Code Error 
Steps” 1, 2, 4, and 7 on page H-57. 


Follow local procedures and have the 
data available from “Return Code Error 
Steps” 1, 2, 4, and 7 on page H-57. 


Recustomize the system, referring to 
the User’s Guide (Setting Up and 
Learning the Workstation Program) to 
calculate the session sizes. 


Code 


241B 


2501 


2502 


2503 


2504 


2505 


2506 


System Loader Return Codes - 24xx or 25xx 


Explanation 


A request was made to 
the loader for storage on 
the XMA card, and there 
was not enough storage 
available for the request. 


The loader issued a DOS 
interrupt X‘21’ function 
call, and DOS failed the 
request with DOS 
ERROR CODE 1. 
INVALID FUNCTION 
NUMBER. 


The loader issued a DOS 
interrupt X‘21’ function 
call, and DOS failed the 
request with DOS 
ERROR CODE 2. FILE 
NOT FOUND. 


The loader issued a DOS 
interrupt X‘21’ function 
call, and DOS failed the 
request with DOS 
ERROR CODE 3. PATH 
NOT FOUND. 


The loader issued a DOS 
interrupt X‘21’ function 
call, and DOS failed the 
request with DOS 
ERROR CODE 4. TOO 
MANY OPEN FILES 
(NO HANDLES LEFT). 


The loader issued a DOS 
interrupt X‘21’ function 
call, and DOS failed the 
request with DOS 
ERROR CODE 5. 
ACCESS DENIED. 


The loader issued a DOS 
interrupt X‘21’ function 
call, and DOS failed the 
request with DOS 
ERROR CODE 6. 
INVALID HANDLE. 


Action to Take 


Follow local procedures and have the 
data available from “Return Code Error 
Steps” 1, 2, 4, and 7 on page H-57. 


Follow local procedures and have the 
data available from “Return Code Error 
Steps” 1, 2, 4, 5, and 6 on page H-57. 


Place the file that could not be found 
on the disk being used and retry the 
operation. If the error persists, follow 
local procedures and have the data 
available from “Return Code Error 
Steps” 1, 2, 4, 5, and 6 on page H-57. 


Place a disk in the drive with the 
correct path or create the path on the 
disk and then retry the operation. If the 
error persists, follow local procedures 
and have the data available from 
“Return Code Error Steps” 1, 2, 4, 5, 
and 6 on page H-57. 


Create a CONFIG.SYS on the IPL disk 
or edit the existing one and increase 
the number of file handles. The 
command in the file is FILES = xx, 
where xx is the number of file handles. 
See the DOS manual! for details on 
setting up your CONFIG.SYS file. If the 
error persists, follow local procedures 
and have the data available from 
“Return Code Error Steps” 1, 2, 4, 5, 
and 6 on page H-57. 


Follow local procedures and have the 
data available from “Return Code Error 
Steps” 1, 2 4, 5, and 6 on page H-57.his 
chapter. 


Follow local procedures and have the 
data available from “Return Code Error 
Steps” 1, 2 4, 5, and 6 on page H-57. 


Appendix H. Return Codes H-23 


System Loader Return Codes - 24xx or 25xx 


H-24 


Code 


2507 


2508 


2509 


250A 


250B 


250C 


250D 


Explanation 


The loader issued a DOS 
interrupt X‘21’ function 
call, and DOS failed the 
request with DOS 
ERROR CODE 7. 
MEMORY CONTROL 
BLOCKS DESTROYED. 


The loader issued a DOS 
interrupt X‘21’ function 
call, and DOS failed the 
request with DOS 
ERROR CODE 8. 
INSUFFICIENT 
MEMORY. 


The loader issued a DOS 
interrupt X‘21’ function 
call, and DOS failed the 
request with DOS 
ERROR CODE 9. 
INVALID MEMORY 
BLOCK ADDRESS. 


The loader issued a DOS 
interrupt X‘21’ function 
call, and DOS failed the 
request with DOS 
ERROR CODE 10. 
INVALID 
ENVIRONMENT. 


The loader issued a DOS 
interrupt X‘21’ function 
call, and DOS failed the 
request with DOS 
ERROR CODE 11. 
INVALID FORMAT. 


The loader issued a DOS 
interrupt X‘21’ function 
call, and DOS failed the 
request with DOS 
ERROR CODE 12. 
INVALID ACCESS 
CODE. 


The loader issued a DOS 
interrupt X‘21’ function 
call, and DOS failed the 
request with DOS 
ERROR CODE 13. 
INVALID DATA. 


Action to Take 


Follow local procedures and have the 
data available from “Return Code Error 
Steps” 1, 2, 4, 5 and 6 on page H-57. 


Make more storage available and retry 
the request. If it appears that there 
should have been enough storage, 
follow local procedures and have the 
data available from “Return Code Error 
Steps” 1, 2, 4, 5, and 6 on page H-57. 


Follow local procedures and have the 
data available from “Return Code Error 
Steps” 1, 2, 4, 5 and 6 on page H-57. 


Follow local procedures and have the 
data available from “Return Code Error 
Steps” 1, 2, 4, 5 and 6 on page H-57. 


Follow local procedures and have the 
data available from “Return Code Error 
Steps” 1, 2, 4, 5 and 6 on page H-57. 


Follow local procedures and have the 
data available from “Return Code Error 
Steps” 1, 2, 4, 5 and 6 on page H-57. 


Follow local procedures and have the 
data available from “Return Code Error 
Steps” 1, 2, 4, 5 and 6 on page H-57. 


Code 


250F 


2510 


2511 


2512 


2513 
thru 
2553 


System Loader Return Codes - 24xx or 25xx 


Explanation 


The loader issued a DOS 
interrupt X‘21’ function 
call, and DOS failed the 
request with DOS 
ERROR CODE 15. 
INVALID DRIVE WAS 
SPECIFIED. 


The loader issued a DOS 
interrupt X‘21’ function 
call, and DOS failed the 
request with DOS 
ERROR CODE 16. 
ATTEMPT TO REMOVE 
THE CURRENT 
DIRECTORY. 


The loader issued a DOS 
interrupt X‘21’ function 
call, and DOS failed the 
request with DOS 
ERROR CODE 17. NOT 
SAME DEVICE. 


The loader issued a DOS 
interrupt X‘21’ function 
call, and DOS failed the 
request with DOS 
ERROR CODE 18. NO 
MORE FILES. 


The loader issued a DOS 
interrupt X‘21’ function 
call, and DOS failed the 
request with a DOS 
ERROR CODE nn, where 
nn is in hexadecimal. 


Action to Take 


Follow local procedures and have the 
data available from “Return Code Error 
Steps” 1, 2, 4, 5 and 6 on page H-57. 


Follow local procedures and have the 
data available from “Return Code Error 
Steps” 1, 2, 4, 5 and 6 on page H-57. 


Follow local procedures and have the 
data available from “Return Code Error 
Steps” 1, 2, 4, 5 and 6 on page H-57. 


Follow local procedures and have the 
data available from “Return Code Error 
Steps” 1, 2, 4, 5 and 6 on page H-57. 


Follow local procedures and have the 
data available from “Return Code Error 
Steps” 1, 2, 4, 5 and 6 on page H-57. 
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DFT Operations Return Codes - 30xx 


Function ID X‘30’: DFT Operations Return Codes 


H-26 


Return codes beginning with function code X‘30’ indicate that an error 
occurred during DFT operations, except return code X‘3000’, which 
indicates that the requested DFT service was completed successfully. 


If these return codes were issued because of some API interaction, they will 
be followed by another return code that better describes the problem and 
the best action to take; otherwise, follow the “Action to Take” information 
provided with the return code. 


Code 
3000 


3001 


30C7 


30C8 


30C9 


30CA 


30CB 


30CC 


Explanation 


The requested DFT 
service was completed 
successfully. 


An error occurred during 
DFT operations during 
an attempt to sound a 
bell alarm. 


An error occurred during 
DFT initialization 
operations. 


An error occurred during 
DFT operations because 
a nonresettable machine 
check was received. 


An error occurred during 
DFT error-handling 
operations. 


An error occurred during 
DFT error-handling 
operations. 


An error occurred during 
DFT error-handling 
operations. 


An error occurred during 
DFT operations while 
the screen size was being 
changed. 


Action to Take 


None. 


None. 


Follow your local procedures, and have 
the data available from “Return Code 
Error Steps” 1, 2, 5, 6, and 7 on page 
H-57, or re-[PL the system. 


Follow your local procedures, and have 
the data available from “Return Code 
Error Steps” 1, 2, 5, 6, and 7 on page 
H-57, or re-IPL the system. 


Follow your local procedures, and have 
the data available from “Return Code 
Error Steps” 1, 2, 5, 6, and 7 on page 
H-57, or re-IPL the system, 


Follow your local procedures, and have 
the data available from “Return Code 
Error Steps” 1, 2, 5, 6, and 7 on page 
H-57, or re-IPL the system. 


Follow your local procedures, and have 
the data available from “Return Code 
Error Steps” 1, 2, 5, 6, and 7 on page 
H-57, or re-IPL the system. 


Take a system dump, follow local 
procedures, and have the data available 
from “Return Code Error Steps” 1, 2, 5, 
6, and 7 on page H-57, or re-IPL the 
system. 


Code 
30CE 


30CF 


30D0 


30D1 


30D2 


30D3 


30D4 


30D5 


30D6 


DFT Operations Return Codes - 30xx 


Explanation 


An error occurred during 
DFT operations while 
the active logical 
terminal session was 
being found. 


An error occurred during 
DFT operations while 
the active logical 
terminal session was 
being found. 


An error occurred during 
DFT initialization 
operations. 


An error occurred during 
DFT operations while 
the DFT environment 
was being reset. 


An error occurred during 
DFT operations while a 
keystroking task was 
being reinitialized for 
any of the configured 
logical terminals. 


An error occurred during 
DFT operations while a 
DFT inbound data task 
was being reinitialized 
for any of the configured 
logical terminals. 


An error occurred during 
DFT operations while a 
DFT outbound data task 
was being reinitialized 
for any of the configured 
logical terminals. 


An error occurred during 
DFT operations while a 
DFT link task was being 
reinitialized. 


An error occurred during 
DFT operations while a 
window was being 
defined for each 
customized logical 
terminal. 


Action to Take 


Follow your local procedures, and have 
the data available from “Return Code 
Error Steps” 1, 2, 5, 6, and 7 on page 
H-57, or re-IPL the system. 


Follow your local procedures, and have 
the data available from “Return Code 
Error Steps” 1, 2, 5, 6, and 7 on page 
H-57, or re-IPL the system. 


Follow your local procedures, and have 
the data available from “Return Code 
Error Steps” 1, 2, 5, 6, and 7 on page 
H-57, or re-IPL the system. 


Follow your local procedures, and have 
the data available from “Return Code 
Error Steps” 1, 2, 5, 6, and 7 on page 
H-57, or re-IPL the system. 


Follow your local procedures, and have 
the data available from “Return Code 
Error Steps” 1, 2, 5, 6, and 7 on page 
H-57, or re-IPL the system. 


Follow your local procedures, and have 
the data available from “Return Code 
Error Steps” 1, 2, 5, 6, and 7 on page 
H-57, or re-IPL the system. 


Follow your local procedures, and have 
the data available from “Return Code 
Error Steps” 1, 2, 5, 6, and 7 on page 
H-57, or re-IPL the system. 


Follow your local procedures, and have 
the data available from “Return Code 
Error Steps” 1, 2, 5, 6, and 7 on page 
H-57, or re-IPL the system. 


Follow your local procedures, and have 
the data available from “Return Code 
Error Steps” 1, 2, 5, 6, and 7 on page 
H-57, or re-IPL the system. 
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DFT Operations Return Codes - 30xx 


H-28 


Code 
30D7 


30D8 


30D9 


30DA 


30DB 


30DC 


30DD 


30DE 


30DF 


Explanation 


An error occurred during 
DFT initialization 
operations. 


An error occurred during 
DFT initialization 
operations. 


An error occurred during 
DFT operations while a 
task was being linked to. 


An error occurred during 
DFT operations while 
the keyboard was being 
connected for a logical 
terminal. 


An error occurred during 
DFT operations while 
the keyboard connection 
was being made. 


An error occurred during 
DFT operations while a 
keystroke was received 
from a logical terminal 
keyboard. 


An error occurred during 
DFT operations while 
the keystroke was being 
received. 


An error occurred during 
DFT keystroke 
operations. 


An error occurred during 
DFT keystroke 
operations. 


Action to Take 


Follow your local procedures, and have 
the data available from “Return Code 
Error Steps” 1, 2, 5, 6, and 7 on page 
H-57, or re-IPL the system. 


Follow your local procedures, and have 
the data available from “Return Code 
Error Steps” 1, 2, 5, 6, and 7 on page 
H-57, or re-IPL the system. 


Follow your local procedures, and have 
the data available from “Return Code 
Error Steps” 1, 2, 5, 6, and 7 on page 
H-57, or re-[PL the system. 


Follow your local procedures, and have 
the data available from “Return Code 
Error Steps” 1, 2, 5, 6, and 7 on page 
H-57, or re-[PL the system. 


Follow your local procedures, and have 
the data available from “Return Code 
Error Steps” 1, 2, 5, 6, and 7 on page 
H-57, or re-IPL the system. 


Follow your local procedures, and have 
the data available from “Return Code 
Error Steps” 1, 2, 5, 6, and 7 on page 
H-57. Record the number of logical 
terminals you are operating and the 
number of the logical terminal into 
which you were keystroking. 


Follow your local procedures, and have 
the data available from “Return Code 
Error Steps” 1, 2, 5, 6, and 7 on page 
H-57. Then record the number of 
logical terminals with which you are 
operating and the number of the logical 
terminal into which you were 
keystroking. 


Follow your local procedures, and have 
the data available from “Return Code 
Error Steps” 1, 2, 5, 6, and 7 on page 
H-57, or re-IPL the system. 


Follow your local procedures, and have 
the data available from “Return Code 
Error Steps” 1, 2, 5, 6, and 7 on page 
H-57, or re-IPL the system. 


Code 


30E0 


30E1 


302 


30E3 


30E4 


30K5 


30E6 


30K7 


30E8 


30E9 


30KA 


DFT Operations Return Codes - 30xx 


Explanation 


An error occurred during 
DFT keystroke 
operations. 


An error occurred during 
DFT keystroke 
operations. 


An error occurred during 
DFT inbound operations. 


An error occurred during 
DFT inbound operations. 


An error occurred during 
DFT inbound operations. 


An error occurred during 
DFT outbound 
operations. 


An error occurred during 
DFT outbound 
operations. 


An error occurred during 
DFT outbound 
operations. 


An error occurred during 
DFT operations while a 
task was being linked to. 


An error occurred during 
DFT keystroke 
operations. 


An error occurred during 
DFT inbound operations. 


Action to Take 


Follow your local procedures, and have 
the data available from “Return Code 
Error Steps” 1, 2, 5, 6, and 7 on page 
H-57. Record the number of logical 
terminals with-which you are operating 
and the number of the logical terminal 
into which you were keystroking. 


Follow your local procedures, and have 
the data available from “Return Code 
Error Steps” 1, 2, 5, 6, and 7 on page 
H-57, or re-IPL the system. 


Follow your local procedures, and have 
the data available from “Return Code 
Error Steps” 1, 2, 5, 6, and 7 on page 
H-57, or re-IPL the system. 


Follow your local procedures, and have 
the data available from “Return Code 
Error Steps” 1, 2, 5, 6, and 7 on page 
H-57, or re-IPL the system. 


Follow your local procedures, and have 
the data available from “Return Code 
Error Steps” 1, 2, 5, 6, and 7 on page 
H-57, or re-IPL the system. 


Follow your local procedures, and have 
the data available from “Return Code 
Error Steps” 1, 2, 5, 6, and 7 on page 
H-57, or re-IPL the system. 


Follow your local procedures, and have 
the data available from “Return Code 
Error Steps” 1, 2, 5, 6, and 7 on page 
H-57, or re-IPL the system. 


Follow your local procedures, and have 
the data available from “Return Code 
Error Steps” 1, 2, 5, 6, and 7 on page 
H-57, or re-IPL the system. 


Follow your local procedures, and have 
the data available from “Return Code 
Error Steps” 1, 2, 5, 6, and 7 on page 
H-57, or re-IPL the system. 


Follow your local procedures, and have 
the data available from “Return Code 
Error Steps” 1, 2, 5, 6, and 7 on page 
H-57, or re-IPL the system. 


Follow your local procedures, and have 
the data available from “Return Code 
Error Steps” 1, 2, 5, 6, and 7 on page 
H-57, or re-IPL the system. 
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DFT Operations Return Codes - 30xx 


H-30 


Code 
30EB 


30EC 


30ED 


30EE 


30EF 


30F0 


30F1 


30F2 


30F3 


30F4 


30F5 


Explanation 


An error occurred during 
DFT outbound 


operations. 


An error occurred during 
DFT keystroke 


operations. 


An error occurred during 
DFT inbound operations. 


An error occurred during 
DFT outbound 
operations. 


An error occurred during 
DFT keystroke 
operations. 


An error occurred during 
DFT keystroke 
operations. 


An error occurred during 
DFT operations; a 
logical terminal number 
cannot be found. 


An error occurred during 
DFT operations while 
7-color mode was being 
requested. 


An error occurred during 
DFT operations while 
the cursor was being 
drawn. 


An error occurred during 
DFT operations while 
4-color mode was being 
requested. 


An error occurred during 
DFT operations while 
the cursor was being 
drawn. 


Action to Take 


Follow your local procedures, and have 
the data available from “Return Code 
Error Steps” 1, 2, 5, 6, and 7 on page 
H-57, or re-IPL the system. 


Follow your local procedures, and have 
the data available from “Return Code 
Error Steps” 1, 2, 5, 6, and 7 on page 
H-57, or re-IPL the system. 


Follow your local procedures, and have 
the data available from “Return Code 
Error Steps” 1, 2, 5, 6, and 7 on page 
H-57, or re-IPL the system. 


Follow your local procedures, and have 
the data available from “Return Code 
Error Steps” 1, 2, 5, 6, and 7 on page 
H-57, or re-IPL the system. 


Follow your local procedures, and have 
the data available from “Return Code 
Error Steps” 1, 2, 5, 6, and 7 on page 
H-57, or re-IPL the system. 


Follow your local procedures, and have 
the data available from “Return Code 
Error Steps” 1, 2, 5, 6, and 7 on page 
H-57, or re-IPL the system. 


Follow your local procedures, and have 
the data available from “Return Code 
Error Steps” 1, 2, 5, 6, and 7 on page 
H-57, or re-IPL the system. 


Follow your local procedures, and have 
the data available from “Return Code 
Error Steps” 1, 2, 5, 6, and 7 on page 
H-57, or re-IPL the system. 


Follow your local procedures, and have 
the data available from “Return Code 
Error Steps” 1, 2, 5, 6, and 7 on page 
H-57, or re-IPL the system. 


Follow your local procedures, and have 
the data available from “Return Code 
Error Steps” 1, 2, 5, 6, and 7 on page 
H-57, or re-IPL the system. 


Follow your local procedures, and have 
the data available from “Return Code 
Error Steps” 1, 2, 5, 6, and 7 on page 
H-57, or re-IPL the system. 


Code 
30F6 


30F7 


30F8 


30F9 


30FA 


30FB 


30FC 


30FD 


DFT Operations Return Codes - 30xx 


Explanation 


An error occurred during 
DFT operations while 
the OIA was being 
drawn. 


An error occurred during 
DFT operations while 
the OIA was being 
drawn. 


An error occurred during 
DFT operations while 
the cursor was being 
drawn. 


An error occurred during 
DFT operations while a 
character was being 
drawn. 


An error occurred during 
DFT operations while 
the cursor was being 
drawn. 


An error occurred during 
DFT operations while 
the cursor was being 
drawn. 


An error occurred during 
DFT operations while 
the screen was being 
drawn. 


An error occurred during 
DFT operations while 
the screen was being 
drawn. 


Action to Take 


Follow your local procedures, and have 
the data available from “Return Code 
Error Steps” 1, 2, 5, 6, and 7 on page 
H-57, or re-IPL the system. 


Follow your local procedures, and have 
the data available from “Return Code 
Error Steps” 1, 2, 5, 6, and 7 on page 
H-57, or re-IPL the system. 


Follow your local procedures, and have 
the data available from “Return Code 
Error Steps” 1, 2, 5, 6, and 7 on page 
H-57, or re-IPL the system. 


Follow your local procedures, and have 
the data available from “Return Code 
Error Steps” 1, 2, 5, 6, and 7 on page 
H-57, or re-IPL the system. 


Follow your local procedures, and have 
the data available from “Return Code 
Error Steps” 1, 2, 5, 6, and 7 on page 
H-57, or re-IPL the system. 


Follow your local procedures, and have 
the data available from “Return Code 
Error Steps” 1, 2, 5, 6, and 7 on page 
H-57, or re-IPL the system. 


Follow your local procedures, and have 
the data available from “Return Code 
Error Steps” 1, 2, 5, 6, and 7 on page 
H-57, or re-IPL the system. 


Follow your local procedures, and have 
the data available from “Return Code 
Error Steps” 1, 2, 5, 6, and 7 on page 
H-57, or re-IPL the system. 
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Host Interactive Services Return Codes - 32xx 


Function ID X‘32’: Host Interactive Services Return 


Codes 


H-32 


Return codes beginning with function code X‘32’ indicate that an error 
occurred during host interactive services operations, except return code 
X‘3200’, which indicates that the requested host interactive service was 
completed successfully. 


Code 
3200 


3201 


3202 


3204 


3208 


320C 


3210 


Explanation 


The request was 
completed successfully. 


The host session is not 
active. 


There was an invalid 
service request 
parameter. 


The session is not 
connected. 


A system error occurred. 


Byte 0 of the parameter 
list was nonzero on 
request. 


Three requesters (the 
limit) are already 
connected. 


The message you sent 
was rejected. 


Action to Take 


None. 


The port is not geared for the host 
session that the application attempted 
to connect to. Do not attempt to 
connect to a host session that you have 
no attachment for. 


Check the host session ID, fixed-length 
queue ID, and task ID. The task ID 
must be the same one specified on the 
connect request. 


Connect to the host interactive services 
and retry. 


Follow local procedures and have the 
data available from “Return Code Error 
Steps” 1, 2, 4, 5, and 6 on page H-57. 


Set byte 0 of the parameter list to zero 
and retry. 


No more than three applications may 
connect to a host session at one time. 


The device is not in a state to receive 
inbound transmissions. If the host 
keyboard is inhibited, pressing Clear or 
Reset may allow the inbound to work 
on retry. 


For destination/origin, the host 
application may not have indicated that 
it wants a reply from the personal 
computer program. If this does not 
seem to be the case, follow local 
procedures and have the data available 
from “Return Code Error Steps” 1, 2, 4, 
5, and 6 at the end of this chapter. 


CUT Return Codes - 46xx 


Function ID X‘46’: CUT Return Codes 


Return codes beginning with function code X‘46’ indicate that an error 
occurred during CUT operations. 


These return codes will be followed by another return code that better 
describes the problem and the best action to take. Otherwise, follow the 
“Action to Take” information provided with the return code. 


Code 


4601 
thru 
4603 


4604 
thru 
4607 


4608 
thru 
4611 


4612 


4613 
thru 
4616 


Explanation 


An error occurred during 
the CUT second-level 
interrupt handler task. 


An error occurred during 
the CUT hardware 
initialization task. 


An error occurred during 
the CUT keystroke 
handling task. 


An error occurred during 
the CUT keystroke 
transmit task. 


An error occurred during 
the CUT outbound 
control task. 


Action to Take 


Re-IPL the system or take a system 
dump. Then follow local procedures and 
have the dump available as well as the 
data from “Return Code Error Steps” 1, 
2, and 6 on page H-57. 


Re-IPL the system or take a system 
dump. Then follow local procedures and 
have available the dump and the data 
from “Return Code Error Steps” 1, 2, 
and 6 on page H-57. 


Re-IPL the system or take a system 
dump. Then follow local procedures and 
have available the dump and the data 
from “Return Code Error Steps” 1, 2, 
and 6 on page H-57. 


Re-IPL the system or take a system 
dump. Then follow local procedures and 
have available the dump and the data 
from “Return Code Error Steps” 1, 2, 
and 6 on page H-57. 


Re-IPL the system or take a system 
dump. Then follow local procedures and 
have available the dump and the data 
from “Return Code Error Steps” 1, 2, 
and 6 on page H-57. 
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Notepad Operations Return Codes - 51xx 


Function ID X‘51’: Notepad Operations Return Codes 


H-34 


Return codes beginning with function code X‘51’ indicate that an error 
occurred during notepad operations, except return code X‘5100’, which 
indicates that the requested notepad service was completed successfully. 


Code 


5100 


5101 


5102 


5103 


5104 


Explanation 

The requested notepad 
service was completed 
successfully. 


The notepad cannot 


connect to the keyboard. 


The notepad received an 
error indication on a 
READ KEYBOARD 
operation. 


The notepad received an 
error indication while 
attempting a DRAW 
operation. 


The notepad received an 
error indication during 
autokey operations. 


Action to Take 


None. 


Refer to keyboard problem 
determination in the Problem 
Determination Guide and Reference. 


Refer to keyboard problem 
determination in the Problem 
Determination Guide and Reference. 


This error is generally caused by the 
incorrect insertion of a patch or code 
fix. To correct the problem, remove the 
last series of changes to the 
Workstation Program. If this does not 
correct the problem, follow local 
procedures and have the data available 
from “Return Code Error Steps” 1, 2, 
and 6 on page H-57. 


This error generally occurs by an 
incorrect insertion of a patch or code 
fix. To correct the problem, remove the 
last series of changes to the 
Workstation Program. If this does not 
correct the problem, follow local 
procedures and have the data available 
from “Return Code Error Steps” 1, 2, 
and 6 on page H-57. 


Keyboard Services Return Codes - 62xx 


Function ID X‘62’: Keyboard Services Return Codes 


Return codes beginning with function code X‘62’ indicate that an error 
occurred during keyboard operations, except return code X‘6200’, which 
indicates that the requested keyboard service was completed successfully. 


Code 
6200 


6201 


6202 


Explanation 


The requested service 
was completed 
successfully. 


An invalid intercept 
option was specified on 
the Connect to Keyboard 
service request. 
Connectors that wish to 
do READs must set one 
of the intercept option 
bits on and specify an 
input queue ID. The first 
connector to a session 
input must specify 
“intercept all” and must 
provide an input queue 
ID. Others must specify 
“both” or “neither.” 


An error occurred during 
input operations. An 
invalid session ID was 
found in bytes 2 and 38 of 
the parameter list, or the 
length specified in the 
list of keystrokes is 
greater than 255. 


Action to Take 


None. 


If the user is doing a READ, disconnect 
and reconnect using the correct 
intercept option bit and an input queue. 
If the user is connecting, ensure that 
either both or neither of the above 
inputs is in the parameter list. 


This error can also occur if the user is 
trying to connect to a host session that 
has not yet received a power-on reset 
from the control unit. (Missing a 
power-on reset can result from an 
inoperative control unit, a line 
configuration mismatch between the 
control unit and the workstation, or a 
disconnected coaxial cable.) Byte 9 of 
the Connect to Keyboard parameter list 
containing a X‘FF’ is a further 
indication of this and should be treated 
as an abnormal condition. Under these 
conditions, the session has not yet 
completed preparations to accept 
keystrokes. 


Use the session information services to 
determine the correct session ID and 
reissue the request, or correct the 
length of the list of keystrokes to be 
less than or equal to 255. 
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Keyboard Services Return Codes - 62xx 


H-36 


Code 
6204 


6209 


620C 


6210 


Explanation 


On a Connect request, 
two connections are 
already made to the 


requested session ID. No 


more connections are 
allowed until one of 
them disconnects first. 


On all other keyboard 
API requests, you are 
not connected to the 
session whose ID is in 
bytes 2 and 3 of the 
parameter list. 


On a Read Keystroke 
request with a No Wait 
option, there is no 
keystroke available on 
the queue. 


A nonzero return code 
was passed in byte 0 of 
the parameter list when 
the service was 
requested. 


An error occurred during 


input operations. Ona 
Write Keystroke request, 
the last key sent was 


rejected either because it 


was an invalid scan code 
for the session to which 
it was sent, or an inhibit 
condition was present in 
that session. 


Action to Take 


If your program previously did a 
Connect, you are still connected. You 
must issue a Disconnect before 
reconnecting. Otherwise, if your 
program is not one of those connected, 
wait and try again later or notify the 
terminal operator to determine which 
other program is connected so it may be 
terminated, allowing yours to run. 


Determine the correct session ID to use 
and ensure that Connect is issued 
before any other API function is used. 


Poll again for a keystroke, or continue 
with other processing. 


Set byte 0 of the parameter list to zero 
and retry the request. 


Determine whether the last key sent is 
valid for the target session (for 
example, the ESC key is invalid for a 
DFT session or a PAI key has no 
meaning to a personal computer 
session). Other responses depend on 
the indications present in the target 
session (for example, if a key was sent 
and entered into a protected field of a 
DFT session, a reset key must be sent 
to clear the inhibit condition before any 
more keystrokes will be accepted by 
that session). 


Code 


6212 


6214 


Keyboard Services Return Codes - 62xx 


Explanation 


On a Connect operation, 
the Connect has been 
rejected because an 
autokey record is in 
progress. 


On a Write Key 
operation, the last key 
sent was detected as an 
AID key. If the user is 
sending a list of keys, 
the processing of that 
list ended with that key. 


This does not 
mean that an 
error occurred. 


Note: 


On a Connect operation, 
the connect was rejected 
because an autokey 
playback is in progress. 


Action to Take 


Notify the terminal operator that the 
autokey operation must be terminated 
before this or any keyboard API 
function can be processed. 


If the user is processing a list of keys, 
determine how many of them were sent 
by looking at byte 7 of the returned 
parameter list. When the session is 
able to receive more keys, send the 
remainder. 


Notify the terminal operator that the 
autokey operation must be terminated 
before this or any other keyboard API 
function can be processed. 
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Window Management Services Return Codes - 63xx 


Function ID X‘63’: Window Management Services 


Return Codes 


Return codes beginning with function code X‘63’ indicate that an error 
occurred during work station control operations, except return code 
X‘6300’, which indicates that the requested window management service 
was completed successfully. 


Code 
6300 


6301 


6302 


6303 


6304 


6305 


H-38 


Explanation 


The requested service 
was completed 
successfully. 


There is no space for 
additional windows. 


An invalid session ID 
was specified. The ID did 
not match the one 
specified on the Connect 
to Work Station Control 
request. If the function 
that failed was the 
connect, then the session 
ID specified is not within 
the valid range of 
session IDs. 


There is not enough 
storage to relocate 
initialization code. 


The caller is not 
connected to the work 
station control session. 


The work station control 
session is already in use 
by one of the following: 


e Another application 
program 

e The user (by pressing 
the WSCRTL key) 

e The workstation 
program. 


The specified window ID 
already exists on the 
specified screen ID. 


Action to Take 


None. 


To add a window, a window must first 
be deleted from this or another screen. 


Use the session ID that was specified on 
the Connect to Work Station Control 
service request to perform the function. 
If this return code occurs during the 
connect process, then the proper 
session ID for the session is needed. 


Additional storage must be obtained in 
order to load the module. 


Connect to the workstation control 
session before attempting to perform a 
function. 


Try to connect to the workstation 
control session when it is available. 


Either delete the desired window from 
the screen (so it may be put back later) 
or specify another window ID to be 
added. 


Window Management Services Return Codes - 63xx 


Code 
6306 


6307 


6309 


630A 


630B 


630C 


630D 


630E 


630F 


6310 


Explanation 


An invalid screen ID was 
specified. The desired 
screen either does not 
exist or cannot be used 
for the requested 
function. 


The specified window ID 
was not found on the 
specified screen ID. 


The specified window ID 
was not found on Screen 


The user attempted to 
hide a window when it is 
the only window on the 
screen. 


All windows on the 
screen are hidden; the 
next window on the 
chain will be unhidden. 


A nonzero return code 
was passed in byte 0 of 
the parameter list when 
the request was issued. 


The specified screen ID 
is not that of the active 
screen. 


No windows exist on the 
specified screen ID. 


Colors cannot be set on 
for a PC session. 


Kither the row or column 
values sent caused the 
window not to fit fully 
on the screen or 
presentation space, or 
one or both of the values 
were equal to zero. 


Action to Take 


Specify a valid ASCII screen ID to the 
function. 


Specify a valid ASCII ID of a window 
on a screen to perform the function. 


Specify a window ID of a window that 
exists on Screen 0. 


Add at least a second window before 
attempting to hide a window. 


None. 


Set byte 0 of the parameter list to zero 
and retry the request. 


Specify the ID of the active screen or 
make the desired screen active to 
perform the function. 


The function cannot be performed when 
no windows exist on the requested 
screen. 


Provide a non-PC window ID to set 
colors. 


This is an informational return code. 
The window has been placed on the 
screen but has been modified to allow it 
to fit on the screen with correct values. 
The changes will be sent back via the 
parameter list. 
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Window Management Services Return Codes - 63xx 
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Code 


6311 


6312 


Explanation 


Some or all of the values 
sent in the parameter list 
were either not correct 
or caused the window 
not to fit fully on the 
screen or presentation 
space. 


The foreground and 
background colors are 
the same. 


Action to Take 


This is an informational return code. | 
The window has been placed on the 
screen but has been modified to allow it 
to fit on the screen with correct values. 
The changes will be sent back to the 
calling program via the parameter list. 


This is an informational return code. 
You should change colors as desired. 


Copy Services Return Codes - 64xx 


Function ID X‘64’: Copy Services Return Codes 


Return codes beginning with function code X‘64’ indicate that an error 
occurred during copy operations, except return code X‘6400’, which 
indicates that the requested copy service was completed successfully. 


Code 


6400 


6401 


6402 


6403 


6404 


6405 


6406 


6407 


Explanation 


The requested copy 
service was completed 
successfully. 


The selected source is 
not allowed. Itisa 
personal computer 
window in graphics 
mode. 


An invalid session ID 
was passed on request to 
the Connect or 
Disconnect for Copy to 
Personal Computer 
Session services. The 
specified session is not a 
personal computer 
session. 


Input is inhibited in the 
target. A copy operation 
was attempted while the 
keyboard was in an 
input-inhibited state for 
the selected target 
window. 


There is not enough 
storage to relocate the 
initialization code. 


Warning: There is an 
overlapping source and 
target area. The copy 
was successful. 


The source definition in 
the parameter list is 
missing a parameter or 
has invalid information. 


The target definition in 
the parameter list is 
missing a parameter or 
has invalid information. 


Action to Take 


None. 


Select a different source. 


Correct the session ID and retry. 


Wait for the keyboard to “unlock.” 

Try the copy again. 

Verify that the host is operating. If 
the keyboard remains locked, refer 

to keyboard problem determination 

in the Problem Determination Guide 
and Reference. 


at aa a 


Additional storage must be obtained in 
order to load this module. 


Verify the target area. 


Correct the source definition and retry 
the copy. 


Correct the target definition and retry 
the copy. 


Appendix H. Return Codes H-41 


Copy Services Return Codes - 64xx 
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Code 
6409 


640C 


640D 


640E 


640F 


Explanation 


Warning: The source 
and target are not the 
same size. If the source 
is larger than the target, 
truncation occurs. If the 
source is smaller than 
the target, the target 
area is padded with 
blanks and copy. 


The return code passed 
in the parameter list on 
request was not zero. 


The selected target is not 
allowed. Either the 
selected target is a PC 
window that did not doa 
copy connect first, or the 
PC target is in graphics 
mode. 


The target window is 
protected. 


The copying of field 
attributes is not allowed 
unless the target window 
is a PC window that is 
attached to 3270 
keystroking or the target 
is a PC buffer form. 


Action to Take 


Verify the target area. 


Set the return code field in the 
parameter list to zero and retry. 


Select a different target. 


Redefine the target area. 


Attach the window to 3270 keystroking 
or remove the bit in the parameter list 
to copy field attributes or make the 
target a PC buffer. 


Draw Service Return Codes - 67xx 


Function ID X‘67°: Draw Service Return Codes 


Return codes beginning with function code X‘67’ indicate that an error 
occurred during draw operations, except return code X‘6700’, which 
indicates that the requested draw service was completed successfully. 


Code 
6700 


6703 


6708 


670C 


Explanation 


The draw request was 
completed successfully. 


There is not enough 
storage to relocate 
initialization code. 


The parameter list 
definition has a missing 


parameter on the 


request. 


The return code passed 
in the parameter list on 
request was not zero. 


Action to Take 


None. 


Obtain additional storage in order to 
load the module. 


Follow your local procedures, and have 
the data available from “Return Code 
Error Steps” 1, 2, 5, 6, and 7 on page 
H-57, or re-IPL. 


Follow your local procedures, and have 
the data available from “Return Code 
Error Steps” 1, 2, 5, 6, and 7 on page 
H-57, or re-IPL. 
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Presentation Space Services Return Codes - 69xx 


Function ID X‘69’: Presentation Space Services Return 


Codes 


H-44 


Return codes beginning with function code X‘69’ indicate that an error 

occurred during presentation space operations, except return code X‘6900’, 
which indicates that the requested presentation space management service 
was completed successfully. 


Code 
6900 


6902 


6903 


6906 


6907 


6909 


690A 


690B 


Explanation 


The requested 
presentation space 
management service was 
completed successfully. 


The specified session ID 
is unknown. 


The specified offset for 
the display is not within 
the address of the 
presentation space. 


An invalid cursor type 
was specified in the 
parameter list for the 
Display Cursor service 
request. 


An invalid cursor 
address was specified in 
the parameter list for the 
Display Cursor service 
request. 


The specified length is 
invalid in the parameter 
list for the Display 
Presentation Space 
service request. 


An invalid number of 
commands are in the 
presentation space data 
stream. 


An invalid number of 
rows/columns are in the 
presentation space data 
stream for the Define 
Presentation Space 
service request. 


Action to Take 


None. 


The Define Presentation Space function 
will return the session ID to be used 
with all subsequent requests concerning 
this new presentation space. Ensure 
that the specified session ID is one 
returned from the Define Presentation 
Space request. 


Correct the offset supplied in the 
parameter list and retry. 


Correct the cursor type and retry. 


Correct the cursor address and retry. 


Correct the length and retry. 


Correct the number of commands in the 
header of the presentation space data 
stream and retry. 


Correct the row/column information in 
command type 1 of the presentation 
space data stream and retry. 


Presentation Space Services Return Codes - 69xx 


Code 
690C 


690D 


690F 


6910 


6911 


6913 


6914 


6915 


6918 


Explanation 


Byte 0 of the parameter 
list is nonzero on 
request. 


There is invalid data in 
the Set Presentation 
Space Type data stream 
command of the Define 
Presentation Space 
service request. 


A command that had no 
data was found in the 
presentation space data 
stream of the Define 
Presentation Space 
service request. 


A Delete Presentation 
Space request was issued 
for a session ID that is 
an initial resource (that 
is, a configured personal 
computer session). 


One or more of the input 
parameters is not valid. 


The address of the work 
area on request to the 
Define Presentation 
Space service was zero. 


The Define Presentation 
Space service was 
requested, and the 
maximum number of PC 
presentation spaces has 
already been created. 


The Set Presentation 
Space Buffer command 
was missing from the 
presentation space data 
stream of the Define 
Presentation Space 
service request. 


The Set Presentation 
Space Size command was 
missing from the 
presentation space data 
stream of the Define 
Presentation Space 
service request. 


Action to Take 


Set byte 0 of the parameter list to zero 
and retry. 


Correct the presentation space type and 
retry. 


The address supplied on command 03 or 
command 04 was zero. Correct and 
retry. 


A Delete Presentation Space request 
can only be issued for a presentation 
space that was previously defined by 
the Define Presentation Space request. 


Review input parameters and ensure 
they are valid. 


Correct the work area segment address 
and retry the request. 


Another Define Presentation Space 
request cannot be completed until an 
existing presentation space is deleted. 


Correct the presentation space data 
stream to include command 03 and 
retry. 


Correct the presentation space data 
stream to include command 01 and 
retry. 
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Presentation Space Services Return Codes - 69xx 
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Code 
6919 


Explanation 


The Set Presentation 
Space Type command 
was missing from the 
presentation space data 
stream of the Define 
Presentation Space 
service request. 


Action to Take 


Correct the presentation space data 
stream to include command 02 and 
retry. 


Session Information Services Return Codes - 6Bxx 


Function ID X‘6B’”: Session Information Services Return 


Codes 


Return codes beginning with function code X‘6B’ indicate that an error 
occurred during session management operations, except return code 
X‘6B00’, which indicates that the requested session information service was 
completed successfully. 


Code 
6B00 


6B01 


6B02 


6B03 


6B05 


6B06 


6B07 


6B09 


6BOA 


Explanation 


The requested service 
was completed 
successfully. 


All short window names 
are currently in use. 


The session ID in the 
parameter list is outside 
the legal range. 


The long window name 
was not found in the 
session manager table. 


Too many attachments 
were made. The 
maximum attachments 
allowed are 255. 


The session ID in the 
parameter list was not 
found in the session 
manager table, 
indicating that the 
session is no longer 
defined. 


The short window name 
is already in use. 


There is an invalid type 
field in the parameter 
list. 


The environment ID in 
the parameter list was 
not found in the session 
manager table. This 
indicates that either the 


specified environment ID 
is invalid or the specified 


environment ID was 
valid at one time but is 
not currently active. 


Action to Take 


None. 


Delete a window to free a short window 
name. 


Correct the session ID in the parameter 
list and retry. 


Check that the long name is in ASCII. 
Then check the long name spelling. 
Correct and retry. 


You must request the Detach Session 
ID service for the given session ID 
before further attachments will be 
allowed. 


Correct the session ID in the parameter 
list and either retry or ignore the error. 


Choose an unused short window name 
and retry. 


Correct the parameter list and retry. 


Correct the environment ID in the 
parameter list and either retry or 
ignore the error. 
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Code 
6BO0B 


6BOC 


6BOD 


6BOE 


6BOF 


6B11 


6B12 


6B13 


6B14 


Explanation 


The window short name 
was not found in the 
session manager table. 


The return code in the 
parameter list is not zero 
on call. 


There is an invalid 
option code in the 
parameter list. 


The base window was 
not found. This 
indicates that either the 
specified environment ID 
is invalid or the specified 
environment ID was 
valid at one time but is 
not currently active. 


There are no available 
entries in the session 
manager table. No 
additional session can be 
established. 


The session type was not 
found in the session 
manager table. 


The length of the name 
array is incorrect. 


The window short name 
is not in uppercase 
ASCII alphanumeric 
characters. 


Cannot detach from this 
session now. 


Action to Take 


Correct the window short name in the 
parameter list and either retry or 
ignore the error. 


Set the return code field in the 
parameter list to zero and retry. 


Correct the option code and retry. 


Correct the environment ID in the 
parameter list and either retry or 
ignore the error. 


Detach a session ID or wait until a 
session ID becomes free. 


Correct the type field in the parameter 
list or ignore the error. 


Correct the name array length and 
retry. 


The short window name must be 
uppercase ASCII alphanumeric 
characters. Correct and retry. 


Check to make sure you have not 
issued more detaches than attaches. 


Translate Services Return Codes - 6Cxx 


Function ID X‘6C’: Translate Services Return Codes 


Return codes beginning with function code X‘6C’ indicate that an error 
occurred during translate operations, except return code X‘6C00’, which 
indicates that the requested translate service was completed successfully. 


Code Explanation Action to Take 

6C0O0 The requested service None. 
was completed 
successfully. 

6C01 There is an invalid Change the translate type in the 
translate type in the parameter list and retry. 


parameter list. 
6COC ‘Byte 0 of the parameter Set byte 0 of the parameter list to zero 


list was nonzero on and retry. 
request. 
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OIA Services Return Codes - 6Dxx 


Function ID X‘6D’: OIA Services Return Codes 


H-50 


Return codes beginning with function code X‘6D’ indicate that an error 
occurred during operator information area operations, except return code 
X‘6D00’, which indicates that the requested operator information area 
service was completed successfully. 


Code Explanation Action to Take 
6D00 The requested service None. 

was completed 

successfully. 


6D02 A invalid session ID was Correct the session ID and retry. 
specified in the 
parameter list. 


6D0C ‘Byte 0 of the parameter Set byte 0 of the parameter list to zero 
list was nonzero on and retry. 
request. 


3270 Keystroke Emulation Services Return Codes - 6Exx 


Function ID X‘6E’: 3270 Keystroke Emulation Services 


Return Codes 


Return codes beginning with function code X‘6E’ indicate that an error 
occurred during 3270 keystroke emulation operations, except return code 
X‘6E00’, which indicates that the requested 3270 keystroke emulation 


service was completed successfully. 


Code 
600 


6E02 


6E08 


6E0C 


Explanation 


The requested service 
was completed 
successfully. 


On a Connect request, 
the specified 
presentation space has 
not been defined to 
accept 3270 keystroking 
emulation. 


On a Read AID Key 
request, the specified 
presentation space has 
not been connected for 
3270 keystroking 
emulation. 


A system error occurred 
during 3270 keystroke 
emulation operations. 


Byte 0 of the parameter 
list was nonzero on 
request. 


Action to Take 


None. 


Use the Define Presentation Space 
service to create a presentation space 
that is defined to accept 3270 
keystroking emulation. Specify this 
presentation space on the Connect for 
3270 Keystroke Emulation service 
request. 


Correct the specified session ID and 
request the READ AID Key service 
again. 


Follow local procedures and have the 
data available from return code error 
step 9 at the end of this chapter. 


Set byte 0 of the parameter list to zero 
and retry. 
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Keystroke Definition Return Codes - 6Fxx 


Function ID X‘6F’: Keystroke Definition Return Codes 


H-52 


Return codes beginning with function code X‘6F’ indicate that an error 
occurred during 3270 keystroke definition initialization, except return code 
X‘6F00’, which indicates that the requested 3270 keystroke definition 
service was completed successfully. 


Code Explanation Action to Take 
6F00 The keystroke definition None 
initialization was 


completed successfully. 


6F01 An ID request was issued Refer to the Guide to Operations and 
to the keyboard with no run the keyboard diagnostics. 


response. 
6F02 An unsupported or Check that the switch settings on the 
invalid ID was returned Model 1A keyboard are off. If they are 
from the keyboard. off, the keyboard is defective. In other 
cases, the keyboard is defective or 
incompatible. 


Error Handler Return Codes - 72xx 


Function ID X‘72’: Error Handler Return Codes 


Return codes beginning with function code X‘72’ indicate that an error 
occurred during error handler operations. 


Code 
7201 


7202 


7203 


7204 


7205 


7206 


Explanation 


A component is trying to 
report an undefined 
return code to the error 
handler. 


A component is trying to 
add a return code to the 
error handler error table, 
but the table is full. 


A component is trying to 
add a return code to the 
error handler error table 
with an invalid severity. 


A dump was requested 
using “TRACE OFF /d.” 


A dump was requested by 
pressing the NMI 
pushbutton. 


A dump was requested by 
pressing the ALT + 
CTRL + TEST keys. 


Action to Take 


This return code is followed by a 
second return code. Follow the 
directions given in the “Action to 


Take” column for that return code. 


This return code is followed by a 
second return code. Follow the 
directions given in the “Action to 


Take” column for that return code. 


This return code is followed by a 
second return code. Follow the 
directions given in the “Action to 


Take” column for that return code. 


None. 


None. 


None. 
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Dump Task Return Codes - 7Fxx 


Function ID X‘7F’: Dump Task Return Codes 


H-54 


Return codes beginning with function code X‘7F’ indicate that an error 
occurred during dump task operations. 


Code 
7F01 


7FFF 


7F02 


7F03 


Explanation 


An error occurred during 
system startup before the 
error handler could be 
loaded into storage and 
successfully initialized. 


An error occurred in the 
multiple DOS portion of 
the workstation program 
before the error handler 
could be loaded into 
storage and successfully 
initialized. 


An error occurred while 
a graphics application 
was being run without a 
graphics adapter. 


A graphics application is 
already in progress in 
another PC window. 


Action to Take 


Re-IPL the system. If the error recurs, 
follow local procedures and submit a 
problem report. 


Re-IPL the system. If the error recurs, 
follow local procedures and submit a 
problem report. 


Press any key to re-IPL your system. If 
the error recurs, follow local 
procedures and submit a problem 
report. 


Press any key to re-IPL your system. If 
the error recurs, follow local 
procedures and submit a problem 
report. 


Enhanced Connectivity Router Return Codes - 81xx 


Function ID X‘81’: Enhanced Connectivity Router 
Return Codes 


Return codes beginning with function code X‘81’ indicate that an error 
occurred during enhanced connectivity router operations. 


Code Explanation Action to Take 
8101 No DFT sessions exist. Rerun customization to add a DFT 
session. 
8104 Insufficient space to Obtain additional storage in order to 
relocate initialization load the module. 
code. 
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User System Extension Return Codes - Dxxx through Fxxx 


Function IDs X‘Dx through Fx’: User System Extension 


Return Codes 


H-56 


Return codes with a function ID of X‘Dx’ through X‘Fx’ are generated by 
user-supplied system extensions. Consult local documentation for the 
meaning of these return codes and the action to take when they are 
encountered. 


Return Code Error Steps 


Return Code Error Steps 


Use these steps only when you are directed to do so by ‘action-to-take’ 
instructions in this chapter. 


I, 


2. 


Record the return code. 


Record the sequence of events that caused the failure, including the 
keys pressed and in what order. 


Turn on the Trace events: 


a. 95 96, 97, 98, 99, 101, and 102 
b. 93, 94, 101, and 102 
c. 101 and 102 


Rerun the application that caused the error until the error recurs. 


If the problem persists, issue the command TRACE OFF /D to take a 
system dump. 


Record the system level. To do this, look at your APAR list as described 
in the Problem Determination Guide and Reference. 


Record the system configuration, which is a list of the hardware, 
including installed options. This may be found in the Guide to 
Operations and the contents of the summary panels. 


a. Insert the customized system diskette in the active drive. 
b. If you have a printer, type: 


TYPE INDCFIG.FIL>PRN and press Enter. 


c. If you do not have a printer, type: 
MORE < INDCFIG.FIL and press Enter. 


Write down the contents of the summary panels. 
Increase the resource requirements in the SIF for the system extension 
in which the error occurred. Refer to the User’s Guide for information 
on SIFs. 


The return code received was accompanied by a message to take a 
dump. Record the return code and take a dump if the error persists. 
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Return Code Error Steps 


Return Code Error Steps 
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Introduction 


Introduction 


The Outbound Data Stream Preprocessor (ODSP) Option allows you to 
preprocess a 3270 outbound data stream with a user system extension 
program. To preprocess an outbound data stream, you must customize your 
workstation program for ODSP. 


Customizing for ODSP 


Initializing ODSP 


[-2 


Before you can customize your workstation program for ODSP, you must 
create a user system extension program. Once you have done this, update 
the customization panels as explained below: 


1. 


Update the Home Panel of customization where it says System 
Extensions under WORKSTATION PROGRAM OPTIONS. If this is 
your only user system extension program, type a 1 under System 
Extensions on the Home Panel. If you already have a number of system 
extension programs indicated, increase this number by 1. 


Complete customization Panel 1.1, filling in all the pertinent 
information about your user system extension program. 


Type “yes” under ODSP on Panel 2 of customization. As a result of 
indicating “yes” to ODSP, the workstation program creates a user exit 
table called INDODSP. INDODSP contains four 4-byte routine address 
entries. Each entry corresponds to one of your four possible host 
sessions and will be used when you initialize ODSP. 


See the IBM 3270 Workstation Program User’s Guide and Reference for 
more information on how to customize for ODSP. 


Now that you have customized for ODSP, each time you IPL your system 
the workstation program loads and gives control to the user system 
extension program you just specified in customization. That system 
extension program must do the following: 


Issue the Supervisory Object Service X‘81’:Name Resolution, to locate 
the user exit table named INDODSP. 


Issue the Supervisory Object Service X‘0E’:Install User Exit Table 
Entries, to initialize the INDODSP table, which contains the routine 
addresses that will process the outbound data stream for each host 
session. If you wish to preprocess data streams from a subset of host 
sessions, then fill in the entries pertaining to those host sessions only. 


ODSP 


e After initialization, return to DOS using the Exit and Remain Resident 
function. 


See Chapter 15 for more information on name resolutions and installing 
user exit table entries. 


Using ODSP 


When an outbound data stream is received and a routine address exists in 
the user extension table, a parameter list is presented to the user system 
extension routine containing pointers and count information pertaining to 
the data stream currently in process. 


ES = Segment address of the parameter list 
DI = Offset address of the parameter list 


The parameter list has the following format on entry to and return from 
your user system extension routine: 


Offset | Length Contents on Entry Contents on Return 


4 1 word Count of bytes in Count of bytes in 
current buffer current buffer 
fe [Toye | Chain indicator 
1 byt 
1 word Reserved Offset address of 
supplementary buffer 
10 1 word Reserved Segment address of 
supplementary buffer 
12 1 word Reserved Count of bytes in 
supplementary buffer 
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Entry Parameters 


Return Parameters 
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The current buffer address contains offset and segment of outbound 
data stream. 


The current buffer count contains the count of bytes present in the 
current buffer. 


Chain indicator 

*100xxxxx’X First 

‘010xxxxx’X Last 

‘000xxxxx’X Middle 

‘110xxxxx’X Only 

*xxIxxxxx’X Local channel command 

The host session number contains the number (0 to 38) of the host 
session for which the data stream was received. This will prevent the 


user extension code from having to declare separate entry points to 
determine the host session number. 


Note: For locally attached 3274/3270PCs, the command is sent first and is 


followed by the remaining 3270 data stream, if present. The user 
system extension will first be passed the command and, subsequently, 
will be called with the data as it is received. 


The current buffer address contains offset and segment of the data 
stream buffer to process first. 


The current buffer count contains the count of bytes present in the data 
stream buffer to process first. 


The supplementary buffer address contains offset and segment of the 
data stream buffer to process second. 


The supplementary buffer count contains the count of bytes present in 
the data stream buffer to process second. 


Note: No change in the Supplementary Buffer fields is necessary if no 


supplementary buffer is provided. If you wish the user extension to 
process a stored data stream first, move the current buffer address and 
count in the parameter list to the respective fields for the 
supplementary buffer. Then store the buffer address and count 
provided by the user extension in the respective fields of the current 
buffer. 


ODSP 


You may change data in the current buffer and use the address and 
count fields of the parameter list to shorten it, either at the front 
(increase the address, decrease the count) or at the end (leave address 
the same, decrease the count). Do not append data to either end of the 
current buffer. This may cause unpredictable results and eventual 
disconnection from the control unit. 3270 buffer addresses (12/14-16 
bit) should be consistent with the current session. 


ODSP Restrictions and Recommendations 


The User System Extension routines that preprocess outbound data streams 
for each logical terminal operate as an internal 3270 Workstation Program 
subroutine. Therefore, the following design restrictions must be observed 
to avoid time-out problems with the control unit: 


e Avoid system waits, including implied waits for I/O, and other 
workstation program API functions. 


e Do not disable interrupts. 
Note: Routines requiring lengthy processing time degrade performance. 


In a multiple-host-session configuration, when processing a data stream for 
one host session, all other host sessions will be locked out from processing 
data streams. Also, this routine gets control from the workstation program 
data stream processor so errors could cause damage to the workstation 
program or system control blocks and modules. | 


For systems with XMA, the user system extension resides in common 
memory and, therefore, should be as compact as possible, since it will 
reduce the size of your PC session. See Chapter 24 for more information 
about user system extensions. 


Sample Program for Outbound Data Stream 
Preprocessing 


Use the following as a sample user system extension program for the ODSP 
option of the 3270 Workstation Program. 
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ODSPTEST.ASM <===== Test code for Outbound Data Stream 


Preprocessing Option 


It is intended for use in testing the Data Stream Preprocessor 
option of 3270 Workstation Program. It operates under all three 
transmission environments (i.e. Local Chnl, SNA, and Bisynch). 

Three variations of data stream modification are tested: 

~ Prefixing a stored data stream to the beginning of the 
current host outbound data stream. 

- Post fixing a stored data stream to the end of the 
current host outbound data stream. 

- Modification of the data stream without pre or post fixing. 

The host outbound data stream contains an escape character to 
Signal which of the operations are required (if any). 

The character follows the WCC character in the data stream and 
is followed in turn by an eight character format name. The 
escape characters are: 
~ The FM character (1EH) is used to signal pre fixing of a 
stored format. 
- The DUP character (1CH) is used to signal post fixing of a 
stored format. 
If modification only is required then the stored format name is 
ended with an 'R'. 


== ==> >> —=> Program Operat ion C= => SSS SSS S555 55> >>== 
The parameter list is first moved into local storage. 


If the data stream segment is first in chain Then 
If the character following the WCC is Field Mark (1EH) Then 


Pick up the next eight characters as a stored data stream name 
and place the stored format as first in the processing. 


Else If the character is DUP (1CH) Then 


Flag for later processing and pick up the next eight characters 
as the stored format name to be appended to the data stream. 


If the data stream segment is last in chain Then 


If an end of chain escape character (i.e. DUP) Then 
Append stored data stream to current data stream 


Move local copy of parameters to 3270 PC's copy 


Return 


Initialization attempts to read an ODSP control file 'ODSPSFCF.CTL' 
from drive C:\ODSPTEST directory, if not found, drive A: is used. 

All test data streams are defined in the control file and are 
read into a control area of ODSPTEST storage. 

Each directory named ODSPTEST on which ever drive contains 
ODSPSFCF.CTL 


ODSP 


ESCP_INC EQU 10 ;Escape character increment 
NAM_SIZE EQU 8 ;Maximum size of a stored name 
SFCFSIZE EQU NAM_SIZE + 11 ;Size of record in SFCF 
MAX NTRS EQU 16 ;Maximum entries in SFI 
MAX SIZE EQU 1920 ;Maximum size of a screen 
BLANK EQU BYTE PTR ' ' Blank space 
A EQU BYTE PTR 'A' ;ASCII character A 
DOSOPEN EQU 3DH ;DOS interrupt to open a file 
DISPLAY EQU 9H ;DOS interrupt to display char. 
DOSCALL EQU 21H :Call to DOS commands 
FIRSTINC EQU 80H ;First in chain flag 
LASTINC EQU 40H ;Last in chain flag 
LCLCMD EQU 20H ;Local channel command flag 
POSTFLAG EQU 01H ;Post fix flag 
DATA_NOP EQU 13H ;Data stream NOP 
PROGRAM SEGMENT ;Define program segment 

ASSUME CS:PROGRAM, DS:PROGRAM, ES:PROGRAM ; 

ORG 0100H ;Make into a COM file 


JMP INIT 


=e 


Oe Nl ee ee ee Ed 


; * Input Parameters * 


INPUT_CB STRUC 


OFFSTCB DW 0 ;OFFSET of current buffer 

SEGADCB DW 0 ;SEGMENT of current buffer 

LENCURB DW 0 ;Length of current buffer 

CHAINID DB 0 ;Chain Indicator 

HOSTNUM DB 0 s;Host Session 

OFFSTSB DW 0 ;OFFSET of Suppl. buffer 

SEGADSB DW 0 ;SEGMENT of Suppl. buffer 

LENSUPB DW 0 ;Length of Suppl. buffer 
INPUT_CB ENDS 


f 


; * Stored Format Name Table * 


DEFSFI STRUC :Definition of SFI 
SCREENME DB NAM_SIZE DUP (' ') ; EBCDIC Name 
SCREENLN DW 0 ; Length of Screen Data 
SCREENAD DW 0 >; Offset of Screen Data 
DEFSFI ENDS 
PAGE 
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LOCAL _CB INPUT 
CB <> ;Local copy of Control Block 


* Stored Format Information * 


COUNT DW 0 ;Count length of screen 
SF_LOC DW 6) ;Stored format offset 
SF_COUNT DW 0 ;Stored format count 
ESCAPE_LOC DW 0 ;Location of escape code 
LCLFLAGS DB 0 ;Local processing flags 
: Error message 
; Erase the screen and highlite top line 
NO_FIND DB OF1H,OC7H ; Write command with unl. kbd. 
DB 011H,040H,O040H ; Set buffer address at R1/Cl 
DB 03CH,05CH,OFOH,OOOH ; RA to R24/C1 (00H) 
DB 012H,040H,O040H ; EUA R1/Cl 
DB 011H,040H,O040H ; Set buffer address at R1/Cl 
DB 01DH,OE8H ; Start field pret. + hilite) 
. ERROR *** 
DB OC5H,0D9H,O0D9H,OD6H,0D9H,040H,05CH,05CH,05CH,040H 
i Unable to 
DB OE4H,095H,081H,082H,093H,085H,040H,0A3H,096H,040H 
; locate sto 
DB 093H,096H,083H,081H,0A3H,085H,040H,0A2H ,0A3H,096H 
; red format 
DB 099H,085H,084H,040H,086H,096H,099H,094H,081H,0A3H 
: named == 
DB 040H,095H,081H,094H,085H,084H,040H,07EH,07EH,06EH,040H 
7 
REQFNAME DB NAM_SIZE DUP(0O) ;Requested format name (EBCDIC) 
NO_FINDL EQU OFFSET SFI - OFFSET NO 
_FIND ;Length of message 
SFI DEFSFI MAX NTRS + 1 DUP (<>) ;Screen Format Information 
PAGE 


PUSH ES ;Save pointers to Control Block 
PUSH DI ; 

PUSH CS ;Set up to put code segment into 
POP DS ; DS (i.e COM file format) 

CLD ;Clear direction flag - auto inc. 
MOV CX,TYPE LOCAL CB ;number of bytes to transfer 
LEA SI,LOCAL_CB.OFFSTCB ;OFFSET of Local CB 

XCHG DiEZoL ;Put contents of parameter 

PUSH ES ; list into my data segment 


[-8 


REPE 
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POP DS ; to free up ES and DI 

PUSH Cs ; registers 

POP ES 

MOVSB 7 

PUSH CS ;Restore DS 

POP DS : 

MOV DI,LOCAL_CB.OFFSTCB ;Put address of cur. buffer 
MOV ES,LOCAL_CB.SEGADCB ; into ES:DI registers 
PAGE 


el ee Kee en lena heel el ne ee eee eee 


CK_LAST: 


CK_LCLCM: 


;IF Data is first in chain 


TEST LOCAL_CB.CHAINID,FIRSTINC 

JZ CK_LAST 

CALL PRCFIC ; Then Process the block for 
: possible stored format 
; If data is last in chain 

TEST LOCAL _CB.CHAINID, LASTINC 

a2 CK_LCLCM 

CALL PRCLIC ; Then Process the block for 

JMP MOVE_LCL : possible stored format 
;Else If local channel command 

TEST LOCAL _CB.CHAINID,LCLCMD 

JZ MOVE_LCL 

CALL PRCLCLCM ; Process local command 


, 
MOVE_LCL: 


MAIN_RET: 


REPE 


CLD ;Clear direction flag (auto inc. 
MOV CX,TYPE LOCAL CB ;Number of bytes in Control Block 
LEA SI,LOCAL_CB.OFFSTCB ;OFFSET of current buffer 
POP DI ;ES:DI from original call 
POP ES : 
MOVSB ;Parameter values to Caller's buf. 
SUB DI,TYPE LOCAL CB ; adjust DI after move 

;Return point for main procedure 
RET ; FAR return to procedure 
ENDP 
PAGE 

Sub-Procedures (=== SS=2 SS >= S=—=SS2 = 
Process Current Buffer First in Chain Procedure 

PROC NEAR ;Process stored format 
TEST LCLFLAGS , LCLCMD : 
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JINZ PRCB_GO 

INC DI ; Increment past command for 
PRCB_GO: ; remote NON-SNA or for SNA 

INC DI ; Increment past WCC 

CMP ES:BYTE PTR [DI],1EH ; If prefixing of format 

JE PRC_PREFIX : is flagged Then process 
: ; Else 

CMP ES:BYTE PTR [DI],1CH ; If post fixing of format 

JE PRC_POSTFIX ; is flagged Then set up 
f 

RET ; Else Return 


ee orm Sm ee cm canes ne em cee rues mm cm sess nes Pe Sm meme ete Seve Creme eee tt ere ee ree Sere CO DS ED) le i SY OD SY ee ee ee ee ee ee ee ee oe 


PRC_POSTFIX: ;Post fix processing set up 
OR LCLFLAGS,POSTFLAG ;Turn on postfix flag 
PRC_PREFIX: ;Prefix processing and Post fix 
MOV ESCAPE_LOC, DI ;Save offset of escape code 
INC DI ;Increment past escape code 
MOV CX,NAM_SIZE ;Number of bytes to transfer 
LEA SI ,REQFNAME ;Offset of local copy 
PUSH DS ;Save current DS 
PUSH ES ;Swap ES and DS around 
POP DS ; 
PUSH CS ; 
POP ES 
XCHG Diet ;Put contents of name field 
REP MOVSB ; into local storage 
POP DS ;Restore DS 


STD ;Set for auto-decrement 
LEA DI,SFI + NAM_SIZE - 1 ;Addr. of end of lst name 
LEA SI,REQFNAME + NAM SIZE - 1 ;Address of current 
MOV CX, COUNT Number of names to check 
COMPARE: ; 

PUSH CX ;Save count of names 
PUSH DI ;Save offset into SFT 
PUSH SI ;Save offset of current name 
MOV CX,NAM_SIZE ;Screen name length 

REPE CMPSB ;Compare screen names in SFI 


; with name in control bytes 
POP SI ; Restore offset to cur name 
POP DI ; Restore offset to end 


POP CX Restore count of names 
JE FOUND2 7 

: If names are not same Then 
ADD DI,TYPE DEFSFI ; increment to next in table 
LOOP COMPARE - 


, 
; If all names are considered 
we are pointed at err msg. 


Move and update the current buffer values 
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FOUND?2: ;When the names match or overrun 


SUB DI,OFFSET SFI + NAM_SIZE - 1 ;Displ. in SFI 
MOV AX,SFI.SCREENLN [DI] ;Length of stored format 
MOV SF_COUNT , AX 
MOV AX,SFI.SCREENAD [DI] ;Address of stored format 
MOV SF_LOC,AX 
MOV CX, NAM_SIZE + 1 ; Nop the eScape code and name 
MOV ES, LOCAL_CB.SEGADCB 
MOV DI, ESCAPE_LOC 7 ain the current buffer 
NOP_NAME: 
MOV ES:BYTE PTR [DI], DATA_NOP 
INC DI 
LOOP NOP_NAME 
TEST LCLFLAGS , POSTFLAG ;When post fix requested 
JNZ FOUND3 ; Skip Buffer update 
LEA SI,REQFNAME + NAM_SIZE - 1 ; When the last char 
CMP BYTE PTR [SI] ,0OD9H ; of SF name is R Then 
JE UPD_OUTP ; Skip Supplemental update 
MOV DX,LOCAL CB.OFFSTCB ;Move current buffer address 
MOV LOCAL_CB.OFFSTSB,DX ; to supplemental position 
MOV DX,LOCAL_CB.SEGADCB ;Same segment address 
MOV LOCAL_CB.SEGADSB,DX ; 
MOV DX,LOCAL_CB.LENCURB ;Move current buffer length 
MOV LOCAL_CB.LENSUPB,DX ; to suppl position 
MOV AX ,ESCP_INC ;Set up modifying constant 
TEST LCLFLAGS , LCLCMD 
JNZ PRCB_ MIN ; either from local channel 
INC AX : or from bisynch 
PRCB_MIN: ; 
SUB LOCAL_CB.LENSUPB,AX ;Decrement length 
ADD LOCAL _CB.OFFSTSB,AX ;Increment offset 


UPD_OUTP: 


MOV AX ,SF_COUNT 

MOV LOCAL _CB.LENCURB,AX 

MOV AX,SF_LOC 

MOV LOCAL_CB.OFFSTCB,AX 

MOV LOCAL _CB.SEGADCB,DS ;data segment has segment 

; address of SFT and SFI 
TEST LCLFLAGS , LCLCMD ;When dealing with the 
JZ FOUND3 
; local channel, 

INC LOCAL_CB.OFFSTCB ; increment the offset address 

DEC LOCAL_CB.LENCURB ; decrement the length 
FOUND3: 7 

RET 7 
PRCFIC ENDP ;Return from subprocedure 
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PAGE 
pESSSsssss=======> Last in Chain Procedure 
PRCLIC PROC NEAR 
; 
TEST LCLFLAGS,POSTFLAG ;If post fixing requested 
JZ PRCLIC_END 
; THEN DO 
LEA SI,REQFNAME + NAM SIZE - 1 ; When the last char 
CMP BYTE PTR [SI],0D9H ; of SF name is R Then 
JE PRCLIC_END ; Skip Supplemental update 
MOV DX,SF_LOC 3; move saved buffer address 
MOV LOCAL_CB.OFFSTSB,DX ; to supplemental position 
MOV LOCAL_CB.SEGADSB,DS ; using DS for segment addr. 
; 
MOV DX ,SF_COUNT ;move saved buffer length 
MOV LOCAL_CB.LENSUPB,DX ; to suppl position 
PRCLIC_END: 
MOV LCLFLAGS , 0 ;Reset local flag regardless 
RET ; 
PRCLIC ENDP ;Return from subprocedure 
PAGE 
pee ene ee +--+ 5 + 5 5 - -e 
pBSSseesess======> Local Channel Command Procedure 
7 ee ee ee UF NS ey ES ND eS ED le ee SE ee ce SE Se Se RE SY GS SE SS SS SS ee ES AE SS RE Gee ES Ge SS Se ES A ED ERS SS SE ES GS SS ee ee ce ee ee ee 
PRCLCLCM PROC NEAR 
pe i a eo ee ee ee nee 
; 
MOV AL,LOCAL_CB.CHAINID 
MOV LCLFLAGS , AL ;Save local chnl flag 
; 
RET 
PRCLCLCM ENDP 7Return from subprocedure 
PAGE 


Ce aI a a ee ee ed 
CEE ee ee ee ee ene ee dD De DE de 
CI ee es 


1 
SERVNAME DB 


‘INDODSP '! ;Name of User Exit Table which 
7; 1s resolved into a UET ID 
UET_ID DW ? ;User exit table resolved ID 
NUMUETE DW 6) ;parameter 
ENTRY1L DW 0 S17 St 
OFENTRY1 DW 0 7to 
SGENTRY1 DW 0 ;install 
ENTRY2 DW 0 ;user 
OFENTRY2 DW 0 7exit 
SGENTRY2 DW 8) ;table 
ENTRY3 DW 0 sentries 
OFENTRY3 DW 0 : 


1-12 


ODSP 


SGENTRY3 DW 0 ;four ! four 
ENTRY4 DW O ; logical ! table 
OFENTRY4 DW 0 ;terminals ! entries 
SGENTRY4 DW 6) 7 
SFT DB 7800H DUP(' ') ;Screen Format Table 
PATHNME DB 'C:\ODSPTEST\ODSPSFCF.CTL',0O ;pathname of SFCF 
SFCFBUFF DB SFCFSIZE DUP(0O) ;buffer for SFCF records 
SFCFHDL DW ? ;file handle for SFCF 
SCRENHDL DW ? ;file handle for screen format 
PATHBUFF DB 'C:\ODSPTEST\, ";structure for pathn 
; to get screen files in SFCF 
EXTASCZ DB "408 0 ;extension put in PATHBUFF to get 
; the screen file 
NXTHSTNM DW 0 ;OFFSET of next position to fill 
; (HOSTID) in host/chain table 
NXTSCR DW 0 ;addr of next position in SFT 
ERROR1 DB ODH,OAH,'Error opening SFCF $',ODH,OAH 
ERROR2 DB ODH,OAH, ‘Error reading from SFCF $',0ODH,OAH 
ERROR3 DB ODH,OAH,'Error opening SFT file $',ODH,OAH 
ERROR4 DB ODH,OAH, 'Error reading SFT file $',ODH,OAH 
ERRORS5 DB ODH,OAH, 'Error closing SFT file $',ODH,OAH 
ERROR6 DB ODH,OAH,'INDODSP name not resolved $',0ODH,OAH 
ERROR7 DB ODH,OAH, 'PUT_UETE function failed $',0ODH,OAH 
PAGE 
INIT PROC NEAR 
MOV AX,CS ;Put initial values into 
MOV DS , AX ; DS and ES 
MOV ES , AX : 
MOV NXTSCR,OFFSET SFT ;Set up to store Screen Data 
MOV NXTHSTNM ,0O ;Set up to store Information 
MOV COUNT,0O 7;Set up count of screen formats 
CLD ;Set up for automatic increment 


INITPROC: 


LEA DX, PATHNME ;address of pathname 

MOV AL,O ;set access code to 'OPEN TO READ' 
MOV AH , DOSOPEN ;open this file (ASCIIZ format) 
INT DOSCALL ‘call DOS 
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SFCFHDL, AX 
READREC 


DX, PATHNME 
PATHNME, A 
PATHBUFF, A 
AL,O 

AH , DOSOPEN 
DOSCALL 


SFCFHDL ,AX 
READREC 


DX ,ERROR1 
ERROR 


;save file handle 
:If there is no error read record 


;address of pathname 

;address of pathname for drive A: 
;address of pathname for drive A: 
;set access code to 'OPEN TO READ' 
open this file (ASCIIZ format) 
:call DOS 


;save file handle 
;If there is no error read record 


s;Else call error routine 
and return to DOS 


~e =e Ne 


ee ee ed kl 


READREC: 


CHECKEND: 


MAX_CAP: 


CX, SFCFSIZE 
DX, SFCFBUFF 
BX , SFCFHDL 
AH, 3FH 
DOSCALL 


CHECKEND 


DX , ERROR2 
ERROR 


COUNT ,MAX_NTRS 


MAX_CAP 


AX, ODH 
STORENME 


DI,NXTHSTNM 


AX,OFFSET NO_FIND ; 
SFI.SCREENAD [DI] ,AX 


AX ,NO_FINDL 


SFI.SCREENLN 


NAME_RES 


;read in first 12 bytes of SFCF 
;address of buffer 

zyput file handle in BX 

sread from file function 

call DOS 


;If there was no error check EOF 


Else Do error routine 
and return to DOS 


7 
tA 
a 
;If at max capacity 

; Then exit file read 

;1f last access to file was EOF 


;Set up error message 
;displacement in SFI for entry 

Location of error message 
;move in addr of screen start 
; Length of error message 


[DI],AX ;Length of screen 


;Then complete initialization 


c 
STORENME : 
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DI ,NXTHSTNM 


AX,NXTSCR 


SFI.SCREENAD[DI] 


CX,NAM_SIZE 
SI,SFCFBUFF 


DI,OFFSET SFI 


;displacement in SFI for entry 
;put buffer OFFSET in SFI 
,AX ;move in addr of screen start 


s;the size of screen name 
;addr of buffer (SOURCE) 
;calculate OFFSET of destination 


ODSP 


Oe ee ee ee Le 


LEA DI,PATHBUFF + 12 ;pathname (destination) 
MOV Cx,8 ;store maximum of 8 chars 
INC SI ;first SFCFBUFF location 
7 
STRPATH: 7 
MOV DL, [SI] ;put char into DL 
CMP DL,ODH ;check for CR 
JE ENDPTH ;if so, end storing 
CMP DL,BYTE PTR BLANK ;is it a blank 
JE ENDPTH ;if so, end storing 
; 
MOV [DI] ,DL ;put char into pathbuff 
INC SI :smext SFCFBUFF location 
INC DI ;next PATHBUFF location 
LOOP STRPATH ;store up to 8 characters 
ENDPTH: 
LEA SI,EXTASCZ ;addr of extension to file 
MOV CxX,4 74 characters long (.SFO) 
REPE MOVSB 


Put extension into name 


ee ee ee re es see me ee ee re ee ce ee ee ee ee ee ee ee ee ene ee eee ee a a ae ae a ae ee eee ee 


MOV DX,OFFSET PATHBUFF ;addr of file name 
MOV AL,O ;access code 'OPEN TO READ' 
MOV AH , DOSOPEN ;open file (ASCIIZ format) 
INT DOSCALL call DOS 
MOV SCRENHDL, AX ;save handle 
JNC READSFT ;If no error read SFT 

i 
LEA DX ,ERROR3 ;Else do error routine 
CALL ERROR > and exit to DOS 
RET ; 


eet ate er meee cers Sm see me Gam Sum ates mm cree came um ormms nn mms meme Smee crue ute ents cy mee me ym me em ety ee ee cee ee Oe weet me wee ne ee woe ee ee ee 


READSFT: 


; 
MOV CX ,MAX_ SIZE ;try to read 1920 characters 
MOV DX,NXTSCR ;addr to put file in 
MOV BX, SCRENHDL ;put handle into BX 
MOV AH, 3FH ;read from file function 
INT DOSCALL :call DOS 
JNC STORESFT ;If no error store SFT info 
LEA DX , ERROR4 ;Else do error routine 
CALL ERROR ; and them return to DOS 
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STORESFT: 


SI,NXTHSTNM 
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;addr to store 


SFI.SCREENLN [SI],AX ;Length of screen 


NXTSCR,AX 


NXTHSTNM,TYPE DEFSFI 


;OFFSET of next screen table entry 
;OFFSET on next info. entry 


CI lel el anes eel ee cee Eh ee A een ee ae ee eee eee ee enemies eee eee tes Ree eee ae ee ee ee ee ee ees 


reinit buffers and ctrs., return to read SFCF 


Cl el ee ele one ee lo ee ene ee eed eee eae eee hen ee eek tok en enn eee ane ae tbe teet end] 


; Close old screen file, 


REINIT: 


° 
f 


LEA 
CALL 
RET 


BX, SCRENHDL 


AH, 3EH 
DOSCALL 


REINIT 


DX, ERROR5 
ERROR 


COUNT 
READREC 


;Put screen handle into BX 
sClose handle function 
;Call DOS 


;1f no error REINIT 


s;Else do error routine 
; and return to DOS 


° 
i 


sIncrement cnt of formats 
sRead the next file 


CI I ee ee ee es eee eee ee ee eee ee el 


NAME_RES: 


? 
PUT_ENTRY: 


1-16 


DI,SERVNAME 


7AH 


CL, OFFH 
PUT_ENTRY 


DX , ERROR6 
ERROR 


UET_ID,DX 
NUMUETE , 2 


AX,DS 
DX ,MAIN 


ENTRY1,0 


;set up registers 
;for a call to 
;name resolution 
interrupt 


;Call 3270 Workstation Program 


;I1f name resolution fails, Then 


: Do error routine 
; and exit to DOS 


;store values 
; 

sin 

; 

;parameter 


e 
t 


slist 


=e 


=e 


=e 


=e 


_REMAIN 


. 
‘ 


EXIT_AND 
_REMAIN: 


e 
/ 
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OFENTRY1,DX H 
SGENTRY1 , AX ;for 
ENTRY2,1 ;install 
OFENTRY2 ,DX : 
SGENTRY2 , AX juser 

; 
ENTRY3,2 sexit 
OFENTRY3 ,DX H 
SGENTRY3 ,AX ;table 
ENTRY4, 3 ;entries 
OFENTRY4 , DX ; 
SGENTRY4 , AX ;interrupt 


AH ,OEH ;put values in 

DX ,UET_ID ;registers for 

DI,DS s;install user exit 

ES,DI ;table entries 

DI ,NUMUETE ;interrupt 

7AH ;Call 3270 Workstation Program 
CL,OFFH ;If put table entry fails, Then 
EXIT_AND 

DX ,ERROR7 Do error routine 

ERROR and exit to DOS 


se se Ne 


DX,OFFSET PATHNME ;OFFSET of next screen table entry 


CL,4 

DX,CL 

DX 

AX,3100H 

DOSCALL ;exit and remain resident 
;end INIT procedure 

NEAR 

AH,DISPLAY ;display character function 

DOSCALL ;Call to DOS routine 
;Return to caller 
send of program segment 

START 
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Notes: 


Notes: 


ai] jrof#L |zeGL | 


x'6B X'73' x'74' 

1 2 3 
End ¥ PgDn 
x’69' X'72' X'7A’ 


X'63 
X'62 


scan code for each key on the IBM 3270 Personal Computer keyboard. 
The hexadecimal scan code appears below the key. 


This diagram shows the key position number and the hexadecimal 
For each key, the key position number appears in a circle above 


the key. 
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This diagram shows the key position number for each key on the 
IBM 3270 Enhanced Personal Computer keyboard. 


For each key, the key position number appears in a circle above 
the key. 
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Add Resource service, coding information 23-8 
Add Window service, coding information 6-14 
APA graphics, changes or limitations on personal 
computer sessions D-37 
API services 
functions of 1-4 
overview 1-2 
overview, diagram of 1-2 
using the interface 1-9 
application program 
call from for Save, Restore, Send and 
Receive G-2 
exception condition structured field B-10 
Interrupt Handler Management services 14-20 
services, list of 1-5 
type PC running on 2-13 
ASCII 
ASCII/ASCII Mnemonics 5-7, A-4 
characters common to all countries A-4 
characters used by U.S. English A-4 
mnemonics common to all countries A-4 
Read Input API 5-7 
Write Keystroke API 5-7 
asynchronous API services processing 3-3 
Attach Session ID service, coding information 4-17 
Attention Identifier (AID) keys, defined 5-5 
attributes, session F-2 
AUTOEXEC.BAT file, using C-3 


background session 2-10 
background, definition 2-10 
BAT files, using C-2 
batch files, using C-2 
bit numbering conventions used in this manual, 
described 2-16, 13-22 
bits, meaning of 
write control character (WCC) D-9 
buffer addresses D-31 


calling Save, Restore, Send, and Receive from your 
application program G-2 
Change Enlarge State service, coding 
information 6-36 
Change Hidden State service, coding 
information 6-33 
Change Screen Background service, coding 
information 6-38 
Change Task’s Priority service, coding 
information 17-14 
Change Window Attributes service, coding 
information 6-92 
Change Window Color service, coding 
information 6-25 
Change Window Position on Presentation Space 
service, coding information 6-29 
Change Window Position on Screen service, coding 
information 6-17 
Change Window Size service, coding 
information 6-21 
character attributes D-7, F-4, F-5 
Claim a Semaphore service, coding 
information 18-3 
Clear Screen service, coding information 6-66 
Close X‘D0’ structured field 
sending from host to 3270 PC 
format B-18 
overview B-12 
sending from 3270 PC to host - 
format B-28 
overview B-20 
coding descriptions 
copy services 10-2 
environment manager services 23-2 
fixed-length queue management services 20-2 
host interactive services 7-2 
interrupt handler management services 21-2 
keyboard services 5-2 
logical timer management services 19-2 
Multi-DOS services 13-2-13-20 
operator information area services 12-2 
presentation space services 8-2 
request services 16-2 
semaphore management services 18-2 
session information services 4-2 
supervisor services 3-2 
supervisory object services 15-2 
system extension message service 24-16 
system extensions 24-2 
task state modifier services 17-2 
translate service 11-2 
window management services 6-2 
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Add Resource service 23-11 
Add Window service 6-16 
Attach Session ID service 4-19 
Change Enlarge State service 6-37 
Change Hidden State service 6-35 
Change Screen Background service 6-40 
Change Task’s Priority service 17-15 
Change Window Attributes service 6-96 
Change Window Color service 6-28 
Change Window Position on Presentation Space 
service 6-32 
Change Window Position on Screen 
service 6-20 
Change Window Size service 6-24 
Claim a Semaphore service 18-5 
Clear Screen service 6-68 
Connect for Copy to PC Session service 10-21 
Connect for 3270 Keystroke Emulation 
service 9-9 
Connect to Host Session service 7-10 
Connect to Keyboard service 5-12 
Connect to Work Station Control service 6-10 
Copy Block service 10-17 
Copy String service 10-10 
Create Component Entry service 15-10 
Create Fixed-Length Queue Entry service 3-11 
Create Fixed-Length Queue service 15-16 
Create Gate Entry service 15-20 
Create Semaphore Entry service 15-13 
Create Task Entry service 15-7 
Create User Exit Table Entry service 15-23 
Define Buffer service 7-29 
Define Presentation Space service 8-9 
Delete Entry service 15-33 
Delete Entry service, coding information 3-16 
Delete Presentation Space service 8-13 
Delete Resource service 23-14 
Delete Window service 6-80 
Dequeue Data service 20-7 
Dequeue Data service, coding information 3-14 
Detach Session ID service 4-16 
Disable Input service 5-32 
Disconnect for Copy to PC Session 
service 10-24 
Disconnect for 3270 Keystroke Emulation 9-12 
Disconnect From Host Session service 7-14 
Disconnect from Keyboard service 5-15 
Disconnect from Work Station Control 
service 6-13 
Display Presentation Space service 8-16 
Enable Input service. 5-35 
Enqueue Data service 20-4 
Get a Request service 16-10 
Get Logical Timer service 19-4 
Get Request Completion service 3-8, 16-16 
ID Resolution service 15-31 
Identify Resource Manager service 23-7 


X-2 


Install a Hardware Interrupt Handler 
service 21-6 

Install an Interrupt Handler service 21-9 

Install User Exit Table Entries service, coding 
information 15-26 

Make a Request service 16-7 

Name Resolution service 3-6, 15-29 

Post Status Code service 5-38 

Purge Queue Data service 20-9 

Query a Semaphore service 18-9 

Query Active Screen service 6-86 

Query Active Task service 17-3 

Query Active Window service 6-83 

Query Base Window service 4-32 

Query Enlarge State service 6-59 

Query Environment Characteristics 
service 23-38 

Query Environment of Window service 4-25 

Query Hidden State service 6-56 

Query Interrupt Vector Contents service 21-11 

Query PC Session PIF Information service 4-29 

Query Resource service 23-16 

Query Screen Background Color service 6-62 

Query Session Cursor service 4-35 

Query Session ID service 4-9 

Query Session Parameter service 4-13 

Query Task’s Environment ID service 23-35 

Query Window Attributes service 6-91 

Query Window Colors service 6-50 

Query Window Names service 6-65 

Query Window Position on Presentation Space 
service 6-53 

Query Window service 6-43 

Query Window Size service 6-46 

Query Windows in Environment service 4-22 

Read AID Key service 9-19 

Read Input service 5-21 

Read Operator Information Area Group 
service 12-13 

Read Operator Information Area Image 
service 12-6 

Read Structured Field service 7-19 

Redraw Screen service 6-74 

Redraw Window service 6-77 

Release a Semaphore service 18-7 

Release Logical Timer service 19-9 

Remove an Interrupt Handler service 21-13 

Reply to a Request service 16-13 

Return to Dispatcher service 17-17 

Select Active Screen service 6-100 

Select Active Window service 6-71 

Send a Signal to a Task service 16-18 

Set Cursor Position service 8-20 

Set Logical Timer service 19-7 

Set Task “Nonpreemptable” service 17-13 

Set Task “Preemptable” service 17-11 

Set Task “Ready” service 17-6 

Set Task “Unready” service 17-9 

Stop/Reset Environment service 23-33 


Suspend/Resume Environment service 23-22 
Switch Presentation Space service 8-22 
System Extension Message service 24-19, 24-21, 
24-24 
Translate Data service 11-8 
Write Keystroke service 5-28 
Write Structured Field service 7-24 
color, changes or limitations on personal computer 
session D-36 
command 
line G-4 
procedures 
file transfer (Send and Receive) C-6 
Save and Restore C-2, C-4 
command line, DOS EXEC G-4 
communication status information 
listed 7-18 
use of with the Read Structured Field 
service 7-18 
completion queue signal 14-8 
completion signal 14-8 
components, defined 14-4 
Connect for Copy to PC Session service, coding 
information 10-19 
Connect for 3270 Keystroke Emulation service, 
coding information 9-7 
Connect to Host Session service, coding 
information 7-4 
Connect to Keyboard services, coding 
information 5-9 
Connect to Work Station Control service, coding 
information 6-7 
Control unit communication session termination on 
personal computer session D-36 
conventions used in the API service 
descriptions 2-16, 13-22 
Copy Block service, coding information 10-12 
copy services 
Connect for Copy to PC Session 10-19 
Copy Block 10-12 
Copy String 10-5 
defined 1-7 
Disconnect for Copy to PC Session 10-22 
copy services:X‘64’: H-41 
Copy String service, coding information 10-5 
Create Component Entry service, coding 
information 15-8 
Create Fixed-Length Queue Entry service, coding 
information 3-9, 15-14 
Create Gate Entry service, coding 
information 15-17 
Create Semaphore Entry service, coding 
information 15-11 
Create Task Entry service, coding information 15-4 
Create User Exit Table Entry service, coding 
information 15-21 
creating a BAT file 
Save and Restore C-2 
Send and Receive C-2, C-6 


creating a batch file 
Save and Restore C-2 
Send and Receive C-2, C-6 
creating an AUTOEXEC.BAT file C-3 
creating objects with names 14-6 
cursor, physical: changes or limitations on personal 
computer sessions D-35 
customization 24-5 
home panel 24-5 
system extension loading 24-5 
CUT hardware initialization:X‘43’: H-33 
CUT host sessions, presentation space size F-8 


[| 


data available signal 14-8 
data stream, manual to use for information, 
listed vii 
debugging a personal computer application 
program E-10 
decimal numbers used in this manual, 
described 2-16, 13-22 
Define Buffer service, coding information 7-25 
Define Presentation Space service, coding 
information 8-4 
Delete Entry service, coding information 3-15, 
15-32 
Delete Presentation Space service, coding 
information 8-11 
Delete Resource service, coding information 23-12 
Delete Window service, coding information 6-78 
Dequeue Data service, coding information 3-12, 
20-5 
Detach Session ID service, coding information 4-14 
DFT host session presentation space size F-7 
DFT operations:X‘30’: H-26 
Disable Input service, coding information 5-30 
Disconnect for Copy to PC Session service, coding 
information 10-22 
Disconnect for 3270 Keystroke Emulation service, 
coding information 9-10 
Disconnect from Host Session service, coding 
information 7-11 
Disconnect from Keyboard service, coding 
information 5-13 
Disconnect From Work Station Control service, 
coding information 6-11 
dispatching tasks 14-11 
Display Presentation Space service, coding 
information 8-14 
DOS EXEC function call G-3 
command line G-4 
environment string G-3 
file control blocks G-4 
take over hardware interrupts 14-17 
take over software interrupts 14-18 
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DOS function calls 14-18 
EXEC G-3 
invoke Save, Restore, Send and Receive G-2 
SETBLOCK G-2 
DOS SETBLOCK function call G-2 
DOS subsystem services:X‘22’ or X‘23’: H-16 
DOS, levels supported by the Workstation 
Program iv 
draw service:X‘67’: H-43 
dump task:X‘7F’:  H-54 
duplicate names 14-6 
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EBCDIC control character I/O codes between host 
and IBM 3270 Personal computer D-5 
Enable Input service, coding information 5-33 
enhanced graphics adapter (EGA) 
defined 1-8 
extended field bit assignment F-5 
Enqueue Data service, coding information 20-3 
environment 
defined 1-8 
string G-3 
environment manager services 
Add Resource 23-8 
coding information 23-2 
Delete Resource 23-12 
Identify Resource Manager 23-4 
Query Environment Characteristics 23-36 
Query Resource 23-15 
Query Task’s Environment ID 23-34 
requesting the 23-2 
Stop/Reset Environment 23-23 
Suspend/Resume Environment 23-17 
environment manager services:X‘13’: H-11 
Erase/Reset structured field 
format D-14 
ID code D-12 
error handler:X‘72’: H-53 
error service, system extension 24-16 
error steps H-57 
events, signals 14-8 
exception handling B-8 
EXEC function call G-3 
extended field attributes D-7, F-4, F-5 


failure, changes or limitations on personal computer 
sessions D-36 

field attributes D-6, F-3 

file control blocks G-4 

file control blocks, DOS EXEC G-4 


X-4 


file transfer commands (Send and Receive) 
BAT file to invoke, using C-2 
DOS function. calls to invoke, using G-2 
programmed command procedure to invoke, 
using C-6 
fixed-length queue 
creating 3-3 
deleting 3-4 
obtaining data from 3-3 
fixed-length queue management services 
Dequeue Data 20-5 
Enqueue Data 20-3 
introduction 14-16 
Purge Queue Data 20-8 
fixed-length queues, definition 14-5 
foreground, definition 2-10 
full screen with APA mode, changes or limitations 
on personal computer session D-37 
functions the API provides 1-4 


gate names 3-2 

gate, defined 3-2 

gates, definition 14-6 

generic signal 14-8 

Get a Request service, coding information 16-8 

Get Logical Timer service, coding information 19-3 

Get Request Completion service, coding 
information 3-7, 16-14 

global software interrupt handlers 14-19 
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hardware interrupt handlers 14-16 
hardware interrupts 
DOS function calls 14-17 
Install a Hardware Interrupt Handler 
service 14-17 
Install an Interrupt Handler service 14-18 
interrupt handler considerations 14-18 
hexadecimal numbers used in this manual, 
described 2-16, 13-22 


host interactive services 


Connect to Host Session 7-4 
Define Buffer 7-25 
defined 1-6 
Disconnect from Host Session 7-11 
Read Structured Field 7-15 
Write Structured Field 7-20 

host interactive services:X‘32’: H-32 
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IBM Macro Assembler manual, listed vii 
IBM 3270 data stream manual, listed vii 
ID Resolution service, coding information 15-30 
Identify Resource Manager service, coding 
information 23-4 
inbound 3270 data stream for partition 0 
Read Buffer format D-19 
Read Buffer format in extended field and 
character mode D-19 
Read Buffer format in field reply mode D-19 
Read Modified All format D-18 
Read Modified format D-18 
Short Read format D-18 
inbound 3270 data stream structured field 
input control B-6 
inbound 3270 data stream structured fields 
Auxiliary Device Query Reply structured field 
format D-25 
character set descriptors D-24 
Character Sets Query Reply structured 
field D-238 
Color Query Reply structured field format D-27 
DDM Query Reply structured field format D-25 
defined B-3 
Direct Access self-defining parameter D-26 
Document Interchange Architecture Query 
Reply structured field format D-26 
Highlight Query Reply structured field 
format D-28 
Implicit Partition Query Reply structured field 
format D-29, D-30 
character cell dimensions D-29 
implicit partition default and alternate 
screen size D-29 
self-defining parameters D-30 
Reply Modes Query Reply structured field 
format D-24 
Usable Area Query structured field D-22 
INCTRL B-6 
input control B-6 
See also INCTRL 
input queue size 5-11 
Insert and Insert Data 
sending X‘DO’ from host to 3270 PC 
format B-15 
Insert and Insert Data, structured fields 
sending X‘DO0’ from host to 3270 PC 
overview B-12 
Install a Hardware Interrupt Handler service 
take over hardware interrupt 14-17 
Install an Interrupt Handler service 
take over hardware interrupts 14-18 
take over software interrupts 14-19 
Install User Exit Table Entries service, coding 
information 15-24 


interface 
codes, host and 3270 PC D-3 
structured field 
exception handling B-8 
query reply format B-4 
read partition query format B-4 
verifying operational B-4 
interrupt handler management services 
application program uses 14-20 
Install a Hardware Interrupt Handler 21-4 
Install a Hardware Interrupt Handler service, 
coding information 21-4 
Install an Interrupt Handler 21-7 
Install an Interrupt Handler service, coding 
information 21-7 
introduction 14-16 ; 
Query Interrupt Vector Contents 21-10 
Remove an Interrupt Handler 21-12 
interrupt handlers 14-16 
DOS EXEC function call 14-17 
DOS function calls 14-18 
global software 14-19 
hardware 14-17 
hardware interrupt considerations 14-18 
hardware interrupts 14-17 
Install a Hardware Interrupt Handler 
service 14-17 
Install an Interrupt Handler service 14-18, 
14-19 
local software 14-19 
software interrupt handler considerations 14-19 
software interrupts 14-18 
Interrupt X‘10’ 2-8 


keyboard services 
Connect to Keyboard 5-9 
defined 1-6 
Disable Input 5-30 
Disconnect from Keyboard 5-13 
Enable Input 5-33 
how to request 5-8 
Post Status Code 5-36 
Read Input 5-16 
return codes 5-8 
use of 5-7 
Write Keystroke 5-22 
keyboard services:X‘62’: H-35 
keystroke definition services:X‘6E’: H-52 
Keystroke Emulation 
connect for 3270 keystroke emulation 9-7 
disconnect for 3270 keystroke emulation 9-10 
field attribute definition 9-2 
presentation space format 9-4 
Read AID key 9-13 
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requesting 9-5 

return codes 9-5 

return codes :X‘6Exx’ H-51 
keytop characteristics 5-4 


levels of DOS supported by the Workstation 
Program iv 
limitations 
3270 PC D-2 
local software interrupt handlers 14-19 
logical timer management services 
Get Logical Timer 19-3 
introduction 14-15 
Release Logical Timer 19-8 
Set Logical Timer 19-5 
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macro assembler, manual to use for information, 
listed vii 
Make a Request service, coding information 16-3 
make only keys 
defined A-3 
scan codes A-3 
make/break keys 
defined 5-4 
scan codes A-3 
managing resources, system extensions 22-5, 24-26 
moderately well-behaved program 2-10 
Multi-DOS 
application program performance 2-6, 2-7 
Free Storage service 13-15 
guidelines for running 2-6 
support services defined 1-7 
Writing Applications 2-9 
multi-host, simplifying setup and control 1-4 


Name Resolution service, coding information 3-5 
Name Resolution services, coding 
information 15-27 
names, creating objects 14-6 
non-SNA channel commands D-8 
non-3270 PC hardware 
defined 1-3 
restrictions 2-5, 2-11, D-34 
nonstoppable environment, defined 1-3 
notepad operations:X‘51’: H-34 
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notepad sessions 
presentation space size F-8 
restoring, using programmed command 
procedure C-4 
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object ID 14-6 
objects 
components 14-4 
creation 14-3 
deletion 14-3 
fixed-length queues 14-5 
gates 14-6 
names, creating objects 14-6 
semaphores 14-5, 14-14 
SVC table 14-6 
tasks 14-3 
user exit tables 14-6 
ODSP See Outbound Data Stream Preprocessor 
Option 
OIA services:X‘6D’: H-50 
Open X‘DO’ structured field 
sending from host to 3270 PC 
format B-12 
overview B-i1 
sending from 3270 PC to host 
format B-21 
overview B-20 
successful transmission response, format B-14 
unsuccessful transmission response, 
format B-14 
operational interface B-4 
operator information area services 
defined 1-7 
Read Operator Information Area Group 12-7 
Read Operator Information Area Image 12-4 
order of bit numbering used in this manual, 
described 2-16, 13-22 
Outbound Data Stream Preprocessor Option 
customizing for ODSP_ I-2 
entry parameters I-4 
initializing ODSP 1-2 
restrictions and recommendations 1-5 
return parameters I[-4 
sample program 1-5 
using ODSP_ 1-3 
outbound 3270 data stream structured fields 
defined B-3 
Erase All Unprotected 
format D-14 
ID code D-12 
Erase/Write 
format D-14 
ID code D-12 
Erase/Write Alternate 


format D-14 

ID code D-12 
listed D-12 
Write 

format D-14 

ID code D-12 


overview of API services 1-2 
diagram of 1-2 
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PC application program 
debugging E-10 
display interaction B-7 
exception handling B-8 
personal computer session changes or 
limitations D-34 
physical cursor, changes or limitations on personal 
computer session D-35 
PIF 
See Program Information Files 
poorly behaved program 2-10 
Post Status Code service, coding information 5-36 
prerequisite knowledge needed to use the API 
services Vv 
presentation space 
character table F-6 
considerations F-2 
size 
CUT host F-8 
DFT host F-7 
presentation space services 
Define Presentation Space 8-4 
defined 1-6 
Delete Presentation Space 8-11 
Display Presentation Space 8-14 
Set Cursor Position 8-17 
Switch Presentation Space 8-21 
presentation space services:X‘69’: H-44 
presentation space, defined 1-3 
print spooling, changes or limitations on personal 
computer session D-35 
priorities of tasks 14-3 
priorities, Create Task Entry service 15-4 
problem determination 
procedures E-2-E-9 
system error E-2 
using the trace command E-8 
procedures, command 
file transfer C-2 
Save and Restore C-2 
Program Information Files 
creating and modifying 2-4 
defined 2-3 


programmed command procedures 
for file transfer (Send and Receive) C-6 
for Save and Restore C-4 

Purge Queue Data service, coding information 20-8 


Query a Semaphore service, coding 
information 18-8 

Query Active Screen service, coding 
information 6-84 

Query Active Task service, coding 
information 17-3 

Query Active Window service, coding 
information 6-81 

Query Base Window service, coding 
information 4-30 

Query Enlarge State service, coding 
information 6-57 

Query Environment Characteristics service, coding 
information 23-36 

Query Environment of Window service, coding 
information 4-23 

Query Hidden State service, coding 
information 6-54 

Query Interrupt Vector Contents service, coding 
information 21-10 

Query PC Session PIF Information, coding 
information. 4-26 

query reply B-6 

query reply structured field B-4 

Query Resource service, coding information 23-15 

Query Screen Background Color service, coding 
information 6-60 

Query Session Cursor, coding information 4-33 

Query Session ID service, coding information 4-5 

Query Session Parameters service, coding 
information 4-10 

Query Task’s Environment ID service, coding 
information 23-34 

Query Window Attributes service, coding 
information 6-87 

Query Window Colors service, coding 
information 6-47 

Query Window Names service, coding 
information 6-63 

Query Window Position on Presentation Space 
service, coding information 6-51 

Query Window Position on Screen service, coding 
information 6-41 

Query Window Size service, coding 
information 6-44 

Query Windows in Environment service, coding 
information 4-20 
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Read AID Key service, coding information 9-13 
Read Input service, coding information 5-16 
Read Operator Information Area Group service, 
coding information 12-7 
Read Operator Information Area Image service, 
coding information 12-4 
read partition query structured field B-4 
Read Partition structured field 
Query 
format D-15 
ID code D-12 
Read Buffer 
format D-15 
ID code D-12 
Read Modified 
format D-15 
ID code D-12 
Read Modified All 
format D-15 
ID code D-12 
Read Structured Field service, coding 
information 7-15 
Receive command 
BAT file to invoke, using C-2 
DOS function calls to invoke, using G-2 
programmed command procedure to invoke, 
using C-6 
Redraw Screen service, coding information 6-72 


Redraw Window service, coding information 6-75 


Release a Semaphore service, coding 
information 18-6 
Release Logical Timer service, coding 
information 19-8 
Remove an Interrupt Handler service, coding 
information 21-12 
Reply to a Request service, coding 
information 16-11 
request queue signal 14-8 
request services 
defined 1-8 
Get a Request 16-8 
Get Request Completion 16-14 
Make a Request 16-3 
Reply to a Request 16-11 
Send a Signal toa Task 16-17 
requests, tasks 14-7 
resource manager 
defined 22-5, 24-26 
Restore command 
AUTOEXEC.BAT file to invoke, using C-3 
BAT file to invoke, using C-2 
command procedure to invoke, using C-2 
DOS function calls to invoke, using G-2 
Restrictions 
non-3270 PC hardware 2-11, D-34 
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semaphores 14-14 
workstation program 2-5 

return codes H-2 
X‘Dx through Fx’: user system extension H-56 
X‘12’: system services H-3 
X‘13’: environment manager services H-11 
X‘22’ or X‘23’: DOS Subsystem Services H-16 
X‘24’: DOS system loader H-22 
X‘25’: DOS system loader H-22 
X‘30’: DFT operations H-26 
X‘32’: host interactive services H-32 
X‘43’: CUT hardware initialization H-33 
X‘51’: notepad operations H-34 
X‘6B’: session information services H-47 
X‘6C’: translate services H-49 
X‘6D’: OIA services H-50 
X‘6E’: keystroke emulation services H-51 
X‘6F’: keystroke definition services H-52 
X‘62’: keyboard services H-35 
X‘63’: window management services H-38 
X‘64’: copy services H-41 
X‘67: draw service H-43 
X‘69’: presentation space services H-44 
X‘7F’: dump task H-54 
X72’: error handler H-53 
X‘81’: enhanced connectivity router H-55 

Return to Dispatcher service, coding 

information 17-16 


[s| 


Save and Restore 
BAT file to invoke, using C-2 
command procedure to invoke, using C-2 
DOS function calls to invoke, using G-2 
Save command 
BAT file to invoke, using C-2 
command procedure to invoke, using C-2 
DOS function calls to invoke, using G-2 
scan codes 
described A-2 
IBM Enhanced PC Keyboard (MFI Mode) A-16 
IBM Enhanced PC Keyboard (PC Mode) A-13 
IBM PC XT Keyboard (MFI Mode) A-22 
IBM PC XT Keyboard (PC Mode) A-19 
IBM Personal Computer AT Keyboard (MFI 
Mode) A-28 
IBM Personal Computer AT Keyboard (PC 
Mode) A-25 
IBM 3270 PC Keyboard (MFI Mode) A-9 
IBM 3270 PC Keyboard (PC Mode) A-5 
in list of keystrokes, format 5-25 
introduction 5-3 
special A-3 
table of A-2 
scheduling tasks 14-11 


Select Active Screen service, coding 
information 6-98 
Select Active Window service, coding 
information 6-69 
semaphore 
code serialization 14-14 
management 14-14 
restrictions 14-14 
signal 14-8 
semaphore management services 
Claim a Semaphore 18-3 
Query a Semaphore 18-8 
Release a Semaphore 18-6 
semaphore signal 14-8 
semaphores 
definition 14-5 
Send a Signal to a Task service, coding 
information 16-17 
Send and Receive 
BAT file to invoke, using C-2 
DOS function calls to invoke, using G-2 
programmed command procedure to invoke, 
using C-6 
Send command 
BAT file to invoke, using C-2 
DOS function calls to invoke, using G-2 
programmed command procedure to invoke, 
using C-6 
services and gate names 3-2 
session information services 
Attach Session ID 4-17 
defined 1-6 
Detach Session ID 4-14 
Query Base Window 4-30 
Query Environment of Window 4-23 
Query PC Session PIF Information 4-26 
Query Session Cursor 4-33 
Query Session ID 4-5 
Query Session Parameter 4-10 
Query Windows in Environment 4-20 


session information services:X‘6B’: H-47 
session, defined 1-3 
sessions 


CUT host, presentation space size for F-8 
DFT host, presentation space for F-7 
notepad, presentation spaces size for F-8 
personal computer, changes or limitations 
to D-34 
suspended PC sessions 2-10 
Set Cursor and Get structured fields 
sending from 3270 PC to host 
overview B-20 
Set Cursor and Get X‘DO’ structured fields 
sending from 3270 PC to host 
format B-24 
Set Cursor Position, coding information 8-17 
Set Logical Timer service, coding information 19-5 
Set Reply Mode structured field 
format D-13 


ID code D-12 
Set Task “Nonpreemptable” service, coding 
information 17-12 
Set Task “Preemptable” service, coding 
information 17-10 
Set Task “Ready” service, coding information 17-4 
Set Task “Unready” service, coding 
information 17-7 
SETBLOCK function call G-2 
shift state 
format of A-4 
in list of keystrokes, format 5-25 
introduction 5-3 
SIF 
See System Information Files 
SIFs 
creating and modifying 24-9 
software interrupts 
defined 14-18 
DOS EXEC function call 14-18 
DOS function calls 14-18 
global interrupt handlers 14-19 
Install an Interrupt Handler service 14-19 
interrupt handler considerations 14-19 
local interrupt handlers 14-19 
software needed to write programs that use the API 
services iv 
special 5-6 
Stop/Reset Environment service, coding 
information 23-23 
stoppable environment, defined 1-3 
structured field 
exception handling B-8 
PC application program and display 
interaction B-7 
query reply B-6 
query reply format B-4 
read partition query format B-4 
sending X‘D0’ from host to 3270 PC 
Open X‘DO’ structured field, format B-12 
sending X‘D0’ from the host to 3270 PC 
Insert and Insert Data B-12 
successful transmission response, format B-14 
unsuccessful transmission response B-14 
structured fields 
destination/origin B-9 
exception condition B-10 
application program, self defining 
parm. B-10 
format B-10 
sending X‘D0’ from host to 3270 PC 
Close X‘DO’ structured field, format B-18 
Close X‘DO’ structured field, overview B-12 
Insert and Insert Data, format B-15 
sending X‘DO’ from 3270 PC 
Set Cursor and Get X‘DO’ structured fields, 
format B-24 
sending X‘D0’ from 3270 PC to host 
Close X‘DO’ structured field, format B-28 


Index X-9 


Close X‘DO’ structured field, overview B-20 
Open X‘DO’ structured field, format B-21 
Set Cursor and Get structured fields, 
overview B-20 
successful transmission response, format B-14 
supervisor 
components 14-4 
creating objects with names 14-6 
fixed-length queues 14-5 
gates 14-6 
object creation 14-3 
object deletion 14-3 
semaphores 14-5, 14-14 
SVC table 14-6 
tasks 14-3 
user exit table 14-6 
supervisor services 
Create Fixed-Length Queue Entry 3-9 
Delete Entry 3-15 
Dequeue Data 3-12 
Get Request Completion 3-7 
introduction 14-3 
list of 1-7 
supervisor services, Name Resolution 3-5 
supervisory object services 
Create Component Entry 15-8 
Create Fixed-Length Queue Entry 15-14 
Create Gate Entry 15-17 
Create Semaphore Entry 15-11 
Create Task Entry 15-4 
Create User Exit Table Entry 15-21 
defined 1-8 
Delete Entry 15-32 
ID Resolution 15-30 
Install User Exit Table Entries 15-24 
Name Resolution 15-27 
Suspend/Resume Environment service, coding 
information 23-17 
suspended PC sessions 2-10 
SVC table 
definition 14-6 
Switch Presentation Space service, coding 
information 8-21 
synchronous API services processing 3-3 
system errors problem determination E-2 
system extension 
defined 1-3 
extending workstation program 1-5 
System Extension Message service 24-16 
coding 24-18, 24-20, 24-23 
to identify return codes 24-18 
to request informational messages 24-20, 
24-23 
identifying error return codes 24-16 
requesting error messages 24-17 
requesting informational messages 24-17 
system extensions 
coding. 24-2 
creating 24-3 


X-10 


error service 24-16 
how to load 24-13 
initialization code 24-4 
introduction 24-2 
loading 24-13 © 
managing resources 22-5, 24-26 
messages and codes 24-15 
resident code 24-3 
return codes 24-15 
System Extension Message service 24-16 
system information files creation 24-10 
telling workstation program about 24-5 
user supplied 24-5 
user supplied options 24-7 
System Information Files 
creating 24-9 
defined 2-2 
determining the numbers to use 24-10 
modifying 24-9 
options panel 24-10 
system loader:X‘24’: H-22 
system services H-3 


task creating, coding 15-27 
task requests 14-7 
task state modifier services 
Change Task’s Priority 17-14 
Query Active Task 17-3 
Return to Dispatcher 17-16 
Set Task “Nonpreemptable” 17-12 
Set Task “Preemptable” 17-10 
Set Task “Ready” 17-4 
Set Task “Unready” 17-7 
tasks 
definition 14-3 
dispatch activity 14-12 
dispatch cycles 14-11 
dispatcher states 14-12 
dispatching procedure 14-11 
obtaining request completion 14-10 
priorities 14-3 
receiving arequest 14-9 
replying to arequest 14-10 
request from another task 14-9, 14-10 
request to another 14-9 
requests 14-7 
sending requests 14-9 
state modifiers 14-11 
task state modifiers 14-11 
timer signal 14-8 
trace command, using E-8 
Translate Data service, coding information 11-4 
translate services 
defined 1-7 


Translate Data 11-4 
translate services:X‘6C’: H-49 
transmission of buffer addresses 

buffer addresses, described D-31 

in 12/14-bit address mode D-32 

in 16-bit address mode D-32 
typematic keys, defined 5-4 
typematic make/break keys, defined 5-4 
types of signals 14-8 


unsuccessful transmission response, format B-14 
user exit tables 
definition 14-6 
User supplied system extensions 
loading 24-5 
options panel 24-7 
user system extension:X‘Dx through Fx’: H-56 


wait states 14-8 
WCC (write control character) D-9 
well-behaved program 2-10 
window management services 
Add Window 6-14 
Change Enlarge State 6-36 
Change Hidden State 6-33 
Change Screen Background 6-38 
Change Window Attributes 6-92 
Change Window Color 6-25 
Change Window Position on Presentation 
Space 6-29 
Change Window Position on Screen 6-17 
Change Window Size 6-21 
Clear Screen 6-66 
Connect to Work Station Control 6-7 
defined 1-6 
Delete Window 6-78 
Disconnect From Work Station Control 6-11 
Query Active Screen 6-84 
Query Active Window 6-81 
Query Enlarge State 6-57 
Query Hidden State 6-54 
Query Screen Background Color 6-60 
Query Window Attributes 6-87 
Query Window Colors 6-47 
Query Window Names _ 6-63 
Query Window Position on Presentation 
Space 6-51 
Query Window Position on Screen 6-41 
Query Window Size 6-44 
Redraw Screen 6-72 


Redraw Window 6-75 
Select Active Screen 6-98 
Select Active Window 6-69 
window management services:X‘63’: H-38 
window, defined 1-3 
work station control keys 5-6 
work station control, using 1-5 
Workstation Program 
determining level 2-13 
restrictions 2-5 
write control character (WCC) D-9 
write control character reset actions D-10 


Write Keystroke service, coding information 5-22 


Write Structured Field service, coding 
information 7-20 


X‘DO’ structured fields 
sending from host to 3270 PC 


Open X‘DO’ structured field, overview B-11 


sending from 3270 PC to host 


Open X‘D0’ structured field, overview B-20 


X‘DO’ structured fields, host to 3270 PC 
Close X‘DO’ structured field 
format B-18 
overview B-12 
Insert and Insert Data 
format B-15 
overview B-12 
Open X‘DO’ structured field 
format B-12 
overview B-11 
X‘DO’ structured fields, 3270 PC to host 
Close X‘D0O’ structured field - 
format B-28 
overview B-20 
Open X‘DO’ structured field 
format B-21 
overview B-20 
Set Cursor and Get X‘D0’ structured fields 
format B-24 
overview B-20 
XMA card, defined 1-3 


Numerics 


3270 data stream 
attributes D-6 
commands’ B-3, D-8 
exception handling B-8 
fields B-3 
functions D-3 
inbound stream B-3 


Index 
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interface codes D-3 Connect for 3270 Keystroke Emulation 9-7 


manual to use for information, listed vii Disconnect for 3270 Keystroke Emulation 9-10 
orders D-11 Read AID Key 9-13 
outbound stream B-3 3270 limitations D-2 


3270 keystroke emulation services 
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